--- title: JobNimbus API Integration on Truto slug: jobnimbus category: CRM canonical: "https://truto.one/integrations/detail/jobnimbus/" --- # JobNimbus API Integration on Truto **Category:** CRM **Status:** Beta ## MCP-ready AI tools Truto exposes 30 tools for JobNimbus that AI agents can call directly. - **list_all_job_nimbus_activities** — List JobNimbus activities attached to a record or created by a user. Returns: id, content, activityTypeId, activityAction, isPrivate, primaryRecord, relatedRecords, createdAt. The API rejects requests that filter by neither primaryRecordId nor createdById. pageSize max 200, defaults to 100. - **get_single_job_nimbus_activity_by_id** — Get a single JobNimbus activity by id. Returns: id, content, activityTypeId, activityAction, isPrivate, primaryRecord, relatedRecords, createdAt. Required: id. - **update_a_job_nimbus_activity_by_id** — Update a JobNimbus activity by id with a JSON Patch document. Returns the updated activity: id, content, activityTypeId, primaryRecord, createdAt. Required: id. Activities created by a system integration or with a read-only activity type cannot be patched. - **delete_a_job_nimbus_activity_by_id** — Delete a JobNimbus activity by id. Returns an empty 204 response on success. Required: id. Activities created by a system integration or with a read-only activity type cannot be deleted. - **create_a_job_nimbus_activity** — Create a JobNimbus activity attached to a primary record. Returns the created activity: id, content, activityTypeId, primaryRecord, createdAt. Required: content, activityTypeId, activityAction, primaryRecord. - **job_nimbus_activities_bulk_create** — Create multiple JobNimbus activities in one all-or-nothing batch. Each element of items is an activity payload with content, activityTypeId, activityAction, primaryRecord, and relatedRecords. Returns the created activities with id, activityTypeId, primaryRecord, relatedRecords, and createdById. Required: items. - **list_all_job_nimbus_activity_types** — List activity types available for activities in jobnimbus. Returns each activity type with its integer id plus additional fields under attributes; the exact field set is defined upstream. No request parameters. - **list_all_job_nimbus_companies** — List the jobnimbus companies the authenticated user belongs to. Returns a collection of company records, each including its id. Requires no parameters. - **job_nimbus_auth_switch_company** — Switch the active company context for a JobNimbus integration by supplying the target companyId and a refreshToken. Returns a 200 JSON response whose body fields are not documented in the JobNimbus API reference. Required: companyId, refreshToken. - **list_all_job_nimbus_phone_numbers** — List the sending phone numbers configured for text messaging in jobnimbus. Returns the collection of phone number records, each including its id. - **list_all_job_nimbus_conversations** — List text-messaging conversations in JobNimbus, filterable by assigned user, archived state, linked contact or job, contact or agent phone number, and free text. Returns conversation records with id, contactDisplayName, contactPhoneNumber, agentPhoneNumber, contactId, primaryRecord, assignedUserId, tabs, unreadCount, lastReadAt, lastMessageAt, preview, messageCount, archivedAt, createdAt, updatedAt. Paginates with cursor and pageSize (max 200). - **job_nimbus_conversations_counts** — Get conversation counts per inbox tab in JobNimbus: active, mine, unassigned, others and archived, each with its total and unread counts. Returns: tabs. Takes no parameters. - **get_single_job_nimbus_conversation_by_id** — Get a single JobNimbus text-messaging conversation by id. Returns: id, contactDisplayName, contactPhoneNumber, agentPhoneNumber, contactId, primaryRecord, assignedUserId, tabs, unreadCount, lastReadAt, lastMessageAt, preview, messageCount, archivedAt, createdAt, updatedAt. Required: id. - **job_nimbus_conversations_bulk_update** — Update several JobNimbus text-messaging conversations in one call: each item carries a conversation id and a JSON Patch document (replace operations on /assignedUserId, /archived or /primaryRecord). Returns a 207 multi-status list with one result per item: id, status, data (the updated conversation) or error. Required: items. - **update_a_job_nimbus_conversation_by_id** — Update a JobNimbus text-messaging conversation by id using a JSON Patch document with replace operations on /assignedUserId (assign or unassign), /archived (archive or restore) or /primaryRecord (link to a contact or job). Returns the updated conversation with id, contactDisplayName, contactPhoneNumber, agentPhoneNumber, contactId, primaryRecord, assignedUserId, tabs, unreadCount, lastReadAt, lastMessageAt, preview, messageCount, archivedAt, createdAt, updatedAt. Required: id and a JSON Patch array body. - **create_a_job_nimbus_conversation** — Find or create a JobNimbus text-messaging conversation between a contact phone number and one of your sending (agent) phone numbers, optionally attaching it to a primary CRM record (contact or job). Returns the existing or newly created conversation with id, contactDisplayName, contactPhoneNumber, agentPhoneNumber, contactId, primaryRecord, assignedUserId, tabs, unreadCount, lastReadAt, lastMessageAt, preview, messageCount, archivedAt, createdAt, updatedAt. Required: contactPhoneNumber, agentPhoneNumber. - **job_nimbus_conversations_set_read_state_bulk** — Mark several JobNimbus text-messaging conversations as read or unread in one call. Returns a 207 multi-status list with one result per conversation: id, status, data (unreadCount, lastReadAt) or error. Required: conversationIds, read. - **job_nimbus_conversations_set_read_state** — Mark a JobNimbus text-messaging conversation as read or unread, optionally up to a specific message (lastReadMessageId). Returns: unreadCount, lastReadAt. Required: conversation_id. - **list_all_job_nimbus_messages** — List the message history of a jobnimbus conversation. Returns message records including id, body, mediaIds, and scheduledFor. Required: conversation_id. Max 200 per page. - **create_a_job_nimbus_message** — Send a message in a jobnimbus conversation, optionally scheduling it for later delivery and attaching media. Returns the created message including id, body, mediaIds, and scheduledFor. Required: conversation_id. - **get_single_job_nimbus_message_by_id** — Get a single message in a jobnimbus conversation by id. Returns the message record including id, body, mediaIds, and scheduledFor. Required: id and conversation_id. - **update_a_job_nimbus_message_by_id** — Edit a scheduled message in a jobnimbus conversation by id. Returns the updated message including id, body, mediaIds, and scheduledFor. Fails with 409 Conflict if the message was already sent. Required: id and conversation_id. - **delete_a_job_nimbus_message_by_id** — Delete a scheduled message from a jobnimbus conversation by id. Fails with 409 Conflict if the message was already sent. Returns an empty 204 response on success. Required: id and conversation_id. - **list_all_job_nimbus_credit_memos** — List jobnimbus credit memos filed against a record, optionally filtered by status or archive state. Returns: id, status, isArchived. Required: primaryRecordId, primaryRecordType, sort. Max 100 per page. - **get_single_job_nimbus_credit_memo_by_id** — Get a single jobnimbus credit memo by id. Returns: id, status, isArchived. Required: id. A memo the caller may not see is reported the same way as one that does not exist (404). - **create_a_job_nimbus_credit_memo** — Create a jobnimbus credit memo filed against a primary record. Returns the created memo with id, status, and isArchived. Requires lineItems (at least one), primaryRecord, and idempotency_key. - **job_nimbus_credit_memos_bulk_create** — Create 1-200 jobnimbus credit memos in a single all-or-nothing batch. Returns the created memos with id, status, and isArchived. Requires items (1-200) and idempotency_key. - **update_a_job_nimbus_credit_memo_by_id** — Update a jobnimbus credit memo by id using a JSON Patch document. Returns the updated memo with id, status, and isArchived. Required: id and at least one patch operation. Returns 409 when the credit memo is voided. - **delete_a_job_nimbus_credit_memo_by_id** — Delete a credit memo in jobnimbus by id. Returns an empty 204 response on success. Required: id. - **job_nimbus_credit_memos_void** — Void a credit memo in jobnimbus, marking it void so it can no longer be modified. Returns the credit memo with its id and status. Required: credit_memo_id. Fails with 409 if the credit memo is already voided. ## How it works 1. **Link your customer's JobNimbus account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach JobNimbus.** The Proxy API is a 1-to-1 mapping of the JobNimbus API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed JobNimbus as a native CRM for contractor-focused SaaS** — If your product serves roofing, siding, solar, or specialty contractors, JobNimbus is likely their source of truth. Offering a native integration via Truto lets your users sync activities, conversations, and financial records without exporting CSVs or using Zapier. - **Pipe AI voice and SMS intake into the contractor's CRM inbox** — AI receptionist and conversational SaaS products can create conversations and messages directly inside JobNimbus so after-hours customer interactions appear in the same inbox the sales team already uses, with unread flags preserved. - **Sync field sales and canvassing activity in bulk** — Door-to-door and field sales platforms can batch-push knocked doors, calls, and meetings as JobNimbus activities attached to the right contact or job record, eliminating double data entry for reps. - **Push billing adjustments from payment and financing tools** — Payments, financing, and accounting SaaS can create and void credit memos against jobs so the contractor's back office always sees the accurate balance inside JobNimbus. - **Serve franchise and multi-location contractor networks** — Platforms selling into multi-brand or franchise contractors can use the company switch endpoint to route data to the correct business entity under a single authenticated connection. ## What you can build - **Two-way SMS inbox sync** — Create conversations and messages in JobNimbus, update their read state, and keep an external messaging product in lockstep with the native JobNimbus inbox. - **Scheduled outbound messaging** — Queue review requests, appointment reminders, or follow-ups by creating messages with a scheduled send time directly on the contractor's JobNimbus phone number. - **Bulk activity logging for field reps** — Use bulk activity creation to sync a full day of offline canvassing or call activity to the correct primary records in a single API call. - **Automated credit memo issuance** — Generate credit memos with line items against a job when a dispute, refund, or promotional adjustment is triggered in your billing product, with idempotency keys to prevent duplicates. - **Activity type-aware timeline embeds** — Fetch the contractor's configured activity types and render a timeline inside your product that mirrors how notes, tasks, and events are categorized in JobNimbus. - **Multi-company routing for franchise accounts** — Expose a company picker in your UI that uses the JobNimbus auth switch endpoint so a single connection can read and write across every entity a user has access to. ## FAQs ### How do end users authenticate their JobNimbus account? Truto handles the JobNimbus authentication flow for you. Your users connect through a Truto-managed link or embedded flow, and your backend receives a connection ID to make API calls — no need to store or rotate credentials yourself. ### Can a single connection access multiple JobNimbus companies? Yes. JobNimbus supports multi-company contexts, and the auth switch company endpoint lets you route API calls to a specific company entity under the same authenticated session — useful for franchise networks or parent organizations. ### What JobNimbus objects can I read and write today? The current tool set covers activities (list, get, create, bulk create, update, delete), activity types (list), companies (list), phone numbers (list), conversations (list, get, create, update, bulk update, read state, counts), messages (list, get, create, update, delete), and credit memos (list, get, create, bulk create, update, delete, void). ### Does the integration support bulk operations? Yes. You can bulk create activities, bulk create credit memos, bulk update conversations, and set read state on conversations in bulk — which is important for high-volume contractor workflows like end-of-day field activity sync. ### How do I avoid duplicate credit memos from retries? JobNimbus credit memo endpoints accept idempotency keys. Pass a stable key per logical operation so network retries or at-least-once delivery from your worker queue won't create duplicate entries against a job. ### Can I schedule outbound SMS messages through the API? Yes. The create message endpoint supports a scheduledFor parameter, so you can queue messages to be sent later from the contractor's JobNimbus phone number, with replies landing in the native JobNimbus inbox. ### Is there a unified CRM API I can use instead of the native JobNimbus tools? Not yet for this integration — JobNimbus is currently available through its native tools in Truto. If you need a unified CRM schema across multiple contractor CRMs, reach out and we can prioritize mapping JobNimbus into a unified model.