{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"39c1883f-4a7b-4742-949d-e2b6c09ecd6e","name":"JobNimbus Public API","description":"# Getting Started\n\nThis document describes how to construct API requests and handle responses from the JobNimbus API.\n\n# Building your API Request\n\nWhen building your API Request, you will need to pass along a few values: 1.) the content-type, 2.) the authorization (API key), 3.) the base URL, 3.) a set actor (optional), and 4.) your query (optional if performing a GET).\n\n## Supported HTTP Methods\n\nThe JobNimbus API Supports the following HTTP Methods:\n\n- GET\n    \n- PUT\n    \n- POST\n    \n\n## JSON Support\n\nThe JobNimbus API is a REST-like API that allows exchanging data in JSON format, only. JSON responses use the application/json content-type.\n\n```\n{\n\"count\": 1,\n\"results\": [\n    {\n        ...\n        \"first_name\": \"David\",\n        \"display_name\": \"David JACKSON\",\n        \"last_name\": \"JACKSON\",\n        \"...\n    }\n]}\n\n ```\n\n## Base URL\n\nThe base URL for API endpoint requests:\n\n```\nhttps://app.jobnimbus.com/api1/\n\n ```\n\n## Requesting an API Key (Token)\n\nIn order to obtain an API key, customers of JobNimbus must log into their account and go to settings - API -- New API key Select Profile -- Set the integration name (if existing) or type in the name in the Description box -save.\n\nIf you're a developer working on a new integration, you can create a free trial account to develop with at [https://www.jobnimbus.com/trial-signup](https://www.jobnimbus.com/trial-signup).\n\n## Authentication\n\nTo authenticate requests, set an HTTP header named \"Authorization\" to \"Bearer \"\n\nThe API token is a customer admin level token that grants permissions based on the 'Access Profile' that is associated with the token.\n\n_Sample Token_:\n\n```\njilqy9efy8jk79v9\n\n ```\n\n## Setting an Actor\n\nOptional: If the API token is associated with an 'Access Profile' that has admin level permissions, you can optionally pass an 'actor' query string parameter to cause the API request to inherit the permissions of a specific JobNimbus user account. This will also affect the 'Created By' value of the record in JobNimbus. For example, if you have a JobNimbus team member named Samantha Rawlings and her email address is [sam@company.com](https://mailto:sam@company.com), then if you passed her email address as the actor and created a contact in JobNimbus through the API, that contact would show up as having been created by Samantha. Additionally, if Samantha is a limited access user and you were to make a call to 'GET /contacts', the results would only include contacts that Samantha has access to.\n\n_Example_:\n\n```\n\"https://app.jobnimbus.com/api1/contacts?actor=sam@company.com\"\n\n ```\n\n## Common Query Parameters\n\nEach endpoint utilizes common parameters to customize how a request may be formatted, returns specific fields, or executes a requess. Below are the parameters that are available for our most commonly used endpoints (contacts, jobs, and notes):\n\n- **size** - Controls the number of elements returned in the response.\n    \n    - **Default**: 1000\n        \n    - **Range**: 1-1000 (maximum)\n        \n    - **Example**: `?size=100` returns 100 elements\n        \n    - **Note**: Use smaller values for faster response times or when you only need a subset of results\n        \n- **from** - zero based starting point to be used for pagination (default: 0) Example: `?from=1`\n    \n- **sort_field** - which field to sort by (default: date_created). Example: `?sort_field=date_created`\n    \n- **sort_direction** = which direction to sort the results (default: 'desc') `?sort_direction=asc`\n    \n- **fields** - limit which fields to include in response (default: all fields will be included)\n    \n- **filter** - URL encoded JSON filter object. Please see following section.\n    \n- **bulk** - This improves performance by optimistically saving the record. Note that subsequent “search” type queries might not include this record for several seconds. Example: `?bulk=true`\n    \n- **skip** (a comma separated list)- This causes JobNimbus to NOT perform various automated actions. Example: `?skip=automation,notification`\n    \n    - automation - This bypasses any automation triggers, ensuring your automation rules don’t get triggered.\n        \n    - notification - This bypasses sending any type of notification (email, push notification, etc).\n        \n\n## Queries via the API\n\nWithin a GET request via the JobNimbus API, you are able to pass a query using ElasticSearch syntax (with JSON formatting). This query is passed at the end of the base URL within your request following a question mark and equal sign (?=).\n\n_Examples_:\n\nA GET request against the contacts API for a contact with the first name of \"John\":\n\n```\n?filter={\"must\":[{\"term\":{\"first_name\":\"John\"}}]}\n\n ```\n\nA GET request against the contacts API endpoint for all contacts with the first name of \"John\" and last name of \"Smith\" would use a query such as this:\n\n```\n?filter={\"must\":[{\"term\":{\"first_name\":\"john\"}},{\"term\":{\"last_name\":\"smith\"}}]}\n\n ```\n\nReturn all of the records related to a specific JobNimbus contact's or job's JobNimbus id (id/jnid)\n\n```\n?filter={\"must\":[{\"term\":{\"related.id\":\"abc12345\"}}]}\n\n ```\n\nReturn all of the contacts related to a specific JobNimbus contact's JobNimbus id (id/jnid) and a specific workflow name:\n\n```\n?filter={\"must\":[{\"term\":{\"related.id\":\"abc12345\"}},{\"term\":{\"record_type_name\":\"customer\"}}]}\n\n ```\n\nReturn all of the records based on multiple jnids (need to use terms here):\n\n```\n?filter={\"must\":[{\"terms\":{\"jnid\": [\"jnid1\",\"jnid2\"]}}]}\n\n ```\n\nReturn all of the records updated in the last 24 hours:\n\n```\n?filter={\"must\":[{\"range\":{\"date_updated\":{\"gte\":\"now-1d\"}}}]}\n\n ```\n\nReturn all of the records updated after a specific Unix timestamp (1747900000 = Thursday, 22 May 2025 07:46:40 UTC):\n\n```\n?filter={\"must\":[{\"range\":{\"date_updated\":{\"gte\":1747900000}}}]}\n\n ```\n\n## Custom fields\n\nIf you have created custom fields for contacts or jobs, you may have the need to access the information stored in these fields. Custom fields are created via the Contact Fields or Job Fields section of your JobNimbus Settings.\n\nWhen viewing custom fields on a contact or job record from their respective endpoints, the custom fields will typically be labeled with the name assigned to them (i,e. “Date of Loss”) or a system-generated label for older custom fields. These system-generated custom fields will be pre-labeled with the prefix cf\\* annotating a custom field, an underscore, their field type, another underscore, and number for that field (i,e. “cf_string_1”).\n\nThe following custom field types in JobNimbus will be passed in the following data formats via the API:\n\n- Text: String\n    \n- Date: Date\n    \n- Number: Long integer.\n    \n- Decimal: Double integer.\n    \n- Boolean: true/false\n    \n- Options list: string (separated by commas)\n    \n\nYou can update a custom field via the\n\n<a href=\"https://app.jobnimbus.com/customeradmin/Settings.aspx?autotab=Contact-Fields\">Contact Fields</a>\n\nand\n\n<a href=\"https://app.jobnimbus.com/customeradmin/Settings.aspx?autotab=Job-Fields\">Job Fields</a>\n\nsection of your JobNimbus Settings.\n\n_Example_\n\n```\n...\n            \"cf_string_1\": \"Two-leg. Requires sign-off by the spouse.\",\n            \"cf_date_1\": 1550692800,\n            \"Claim Number\": \"124523-f\",\n            \"Date of Loss\": 1550692800\n...\n\n ```\n\n## Guidance on Escaping Special Characters in Json\n\nIn the payload of the request being sent to JobNimbus (the body of the data), there are certain characters in the field values that must be \"escaped\" (specially marked or notated with a backslash). Escaping these characters prevents the request from returning errors such as (415: Unsupport Media Type or 422: Unprocessable Entity).\n\nPlease ensure all JSON payloads escape the following characters:\n\n- Backspace is replaced with `\\b`\n    \n- Form feed is replaced with `\\f`\n    \n- Newline is replaced with `\\n`\n    \n- Carriage return is replaced with `\\r`\n    \n- Tab is replaced with `\\t`\n    \n- Double quote is replaced with `\\\"`\n    \n- Backslash is replaced with `\\\\`\n    \n\n## A Sample API Request\n\n```\ncurl -X GET -H \"Content-Type: application/json\" -H \"Authorization: Bearer <token>\"  \"https://app.jobnimbus.com/api1/contacts?actor=sam@company.com?filter={\"must\":[{\"term\":{\"first_name\":\"John\"}},{\"term\":{\"last_name\":\"Smith\"}}}]}\"\n\n ```\n\n# Error Handling\n\nIt's important that you capture and relay API errors to either the end user or to a log file to assist with troubleshooting. If an API request fails, the HTTP response code will be something other than \"200\" and the response body should contain a helpful error message. Discarding these error messages without displaying them to either the end user or making them available to your customer support team will make troubleshooting difficult.\n\n_JobNimbus will not be able to assist with troubleshooting if errors are not properly captured._\n\n# Requesting Support\n\nIf an API request is failing, please contact [support@jobnimbus.com](https://mailto:support@jobnimbus.com) with the following information:\n\n- The request URL, including the query string\n    \n- The request payload\n    \n- The HTTP response error code and text message","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"3919598","collectionId":"39c1883f-4a7b-4742-949d-e2b6c09ecd6e","publishedId":"S11PpG4x","public":true,"publicUrl":"https://documenter-api.postman.tech/view/3919598/S11PpG4x","privateUrl":"https://go.postman.co/documentation/3919598-39c1883f-4a7b-4742-949d-e2b6c09ecd6e","customColor":{"top-bar":"FFFFFF","right-sidebar":"34495E","highlight":"3498DB"},"documentationLayout":"classic-double-column","version":"8.10.1","publishDate":"2019-08-14T16:02:00.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/S11PpG4x"}