{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"3d2d1930-f69e-44e8-8bd1-26db6dd045a2","name":"Mister James REST-API v1","description":"Welcome to the REST API documentation for the Mister-James CRM software. Our API allows you to seamlessly integrate the powerful features of our CRM solution into your own applications.\n\nThis API is designed to provide developers with maximum flexibility and efficiency. Whether you're building custom integrations, synchronizing data, or generating advanced reports, our API is built to meet your needs. In this documentation, you'll find detailed information about the available endpoints, authentication options, and best practices for a successful implementation.\n\nThe Mister James RESTful API is available at the following endpoint:\n\n[https://hello.mister-james.com/_utalic_release/api/v1](https://hello.mister-james.com/_utalic_release/api/v1)\n\n### OAuth 2.0 Authentication\n\nTo use the **Mister James** API, we provide OAuth 2.0 for secure authentication. Our implementation supports both PKCE (Proof Key for Code Exchange) and non-PKCE authentication, with two grant types: `authorization_code` and `token`.\n\nWe **highly recommend** using the `authorization_code` grant type with PKCE for enhanced security, especially for single-page applications (SPA). If you prefer using the `token` grant type, this must be explicitly enabled in your app settings.\n\n#### Steps to Authenticate\n\n1. **Register a Client App**:  \n    Before using OAuth, you must first create a client app within your **Mister James** account. This can be done in the **API** section under **Settings**. Here you will receive:\n    \n    - `client_id`: A unique identifier for your app.\n        \n    - `client_secret`: A secret key used for server-side authentication (required for non-PKCE flow).\n        \n    - `redirect_uri`: The URI(s) where the authorization server will redirect after the authorization process is completed.\n        \n2. **Authorization Endpoint**:  \n    The endpoint for initiating the OAuth flow is:  \n    `https://hello.mister-james.com/_utalic_release/oauth/v2.0/authorize`\n    \n3. **Token Endpoint**:  \n    After authorization, exchange the authorization code or refresh token using this token endpoint:  \n    `https://hello.mister-james.com/_utalic_release/oauth/v2.0/token`  \n    This endpoint supports both `authorization_code` and `refresh_token` grant types.\n    \n\n#### PKCE Flow (Recommended for SPAs)\n\nPKCE is a security enhancement to OAuth 2.0, designed for public clients (such as single-page applications) that cannot securely store a `client_secret`.\n\n1. Generate a `code_verifier` (a cryptographically random string).\n    \n2. Derive a `code_challenge` from the `code_verifier` using SHA-256.\n    \n3. Send the `code_challenge` with your authorization request to the `/authorize` endpoint.\n    \n4. After the user authorizes the app, you will receive an authorization code.\n    \n5. Exchange this code at the `/token` endpoint, including the `code_verifier`, to obtain access tokens.\n    \n\n#### Grant Types\n\n- **Authorization Code Grant** (`grant_type=authorization_code`):  \n    This is the most secure method and is recommended for server-side and public clients. It supports PKCE and provides an authorization code that is exchanged for an access token.\n    \n- **Token Grant** (`grant_type=token`):  \n    This method provides an access token directly without an intermediate authorization code. It is less secure and should be used only when necessary. This grant type must be enabled explicitly in your app settings.\n    \n\n#### Redirect URI\n\nWhen registering your app, make sure to define the `redirect_uri`, where users will be redirected after completing the authorization. This URI must match exactly with the one provided in the authorization request to avoid errors.\n\n### OAuth 2.0 Authorization and Token Endpoints\n\n#### Authorization Endpoint\n\nThe Authorization Endpoint is where the user is authenticated and grants permission to the application. This is the starting point of the OAuth flow, where the user is redirected to provide consent.\n\n**URL:**  \n`https://hello.mister-james.com/_utalic_release/oauth/v2.0/authorize`\n\n**Required Query Parameters:**\n\n- **response_type**:  \n    Must be set to `code` to initiate the Authorization Code Flow.  \n    _Example_: `response_type=code`\n    \n- **client_id**:  \n    This is the unique identifier of your application, which you received when registering the client app in the Mister James settings.  \n    _Example_: `client_id=YOUR_CLIENT_ID`\n    \n- **redirect_uri**:  \n    The URL where the user will be redirected after successful authorization. This must be preconfigured in the app settings.  \n    _Example_: `redirect_uri=https://your-app.com/callback`\n    \n- **scope** (optional):  \n    Defines the permissions your application is requesting. Scopes control the resources the user grants access to.  \n    _Example_: `scope=read write`\n    \n- **state** (optional):  \n    A random value to prevent CSRF attacks. You will receive this value in the response and can use it to verify the legitimacy of the request.  \n    _Example_: `state=random_state_value`\n    \n- **code_challenge and code_challenge_method** (for PKCE, optional but recommended):  \n    If you're using PKCE, send the `code_challenge` (derived from a `code_verifier`) along with the hash algorithm (usually `S256`).  \n    _Example_: `code_challenge=CODE_CHALLENGE` and `code_challenge_method=S256`\n    \n\n**Example of a complete URL:**\n\n```\nhttps://hello.mister-james.com/_utalic_release/oauth/v2.0/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://your-app.com/callback&scope=read write&state=random_state_value&code_challenge=CODE_CHALLENGE&code_challenge_method=S256\n\n ```\n\nAfter the user completes the authorization process, they will be redirected to the specified `redirect_uri`. The server will append the **Authorization Code** as a query parameter `code` to the URL:\n\n```\nhttps://your-app.com/callback?code=AUTHORIZATION_CODE&state=random_state_value\n\n ```\n\n#### Token Endpoint\n\nAfter receiving the Authorization Code, you use the **Token Endpoint** to exchange it for an Access Token and a Refresh Token. This token allows your application to make requests to protected resources on behalf of the user.\n\n**URL:**  \n`https://hello.mister-james.com/_utalic_release/oauth/v2.0/token`\n\n**Request Type:**  \n`POST`\n\n**Required POST Parameters:**\n\n- **grant_type**:  \n    Must be set to `authorization_code` to complete the Authorization Code Flow. Alternatively, use `refresh_token` to renew an expired token.  \n    _Example_: `grant_type=authorization_code`\n    \n- **code**:  \n    This is the Authorization Code that you received from the Authorization Endpoint.  \n    _Example_: `code=AUTHORIZATION_CODE`\n    \n- **redirect_uri**:  \n    This must be the same URL that was used in the Authorization Endpoint.  \n    _Example_: `redirect_uri=https://your-app.com/callback`\n    \n- **client_id**:  \n    Your application's unique Client ID.  \n    _Example_: `client_id=YOUR_CLIENT_ID`\n    \n- **client_secret** (optional for PKCE, required without PKCE):  \n    The secret key you received when registering the app. If you're using PKCE, this field is not needed.  \n    _Example_: `client_secret=YOUR_CLIENT_SECRET`\n    \n- **code_verifier** (required only for PKCE):  \n    The code that was originally generated and sent with the `code_challenge`.  \n    _Example_: `code_verifier=CODE_VERIFIER`\n    \n\n**Example POST Request:**\n\n```\nPOST /_utalic_release/oauth/v2.0/token HTTP/1.1\nHost: hello.mister-james.com\nContent-Type: application/x-www-form-urlencoded\ngrant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=https://your-app.com/callback&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\n\n ```\n\n**Token Endpoint Response:**\n\nThe Token Endpoint returns a JSON response containing the Access Token and additional information like its expiration time and a Refresh Token:\n\n``` json\n{\n  \"access_token\": \"ACCESS_TOKEN\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600,\n  \"refresh_token\": \"REFRESH_TOKEN\",\n  \"scope\": \"read write\"\n}\n\n ```\n\n- **access_token**:  \n    The token your application will use to make requests to protected API endpoints on behalf of the user.\n    \n- **token_type**:  \n    Usually `Bearer`, meaning you will send the Access Token in the HTTP headers of your API requests as `Authorization: Bearer ACCESS_TOKEN`.\n    \n- **expires_in**:  \n    The lifetime of the Access Token in seconds. In this example, `3600` means the token is valid for one hour.\n    \n- **refresh_token**:  \n    This token can be used to request a new Access Token without having the user go through the authorization process again.\n    \n\n#### Renewing the Token with the Refresh Token\n\nOnce the Access Token expires, you can call the **Token Endpoint** again, using the **Refresh Token** to obtain a new Access Token. This allows the user to stay authenticated without re-authorizing.\n\n**Example POST Request with Refresh Token:**\n\n```\nPOST /_utalic_release/oauth/v2.0/token HTTP/1.1\nHost: hello.mister-james.com\nContent-Type: application/x-www-form-urlencoded\ngrant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\n\n ```\n\n**Server Response:**\n\n``` json\n{\n  \"access_token\": \"NEW_ACCESS_TOKEN\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600,\n  \"refresh_token\": \"NEW_REFRESH_TOKEN\",\n  \"scope\": \"read write\"\n}\n\n ```\n\nThe new Access Token can then be used to make requests to the API, and the new Refresh Token can be stored for future token renewals.\n\n### Revoking Tokens\n\nIf you need to invalidate a user's `access_token` or `refresh_token`, you can use the **Revoke Endpoint**. This is useful if a user logs out or if you want to manually revoke a token for security reasons. Once revoked, the token can no longer be used to access protected resources.\n\n**URL:**  \n`https://hello.mister-james.com/_utalic_release/oauth/v2.0/revoke`\n\n**Request Type:**  \n`POST`\n\n**Required POST Parameters:**\n\n- **token**:  \n    The token you wish to revoke. This can be either an `access_token` or a `refresh_token`.  \n    _Example_: `token=ACCESS_TOKEN` or `token=REFRESH_TOKEN`\n    \n- **client_id**:  \n    Your application's unique Client ID.  \n    _Example_: `client_id=YOUR_CLIENT_ID`\n    \n- **client_secret**:  \n    The secret key associated with your Client ID.  \n    _Example_: `client_secret=YOUR_CLIENT_SECRET`\n    \n\n**Example POST Request:**\n\n```\nPOST /_utalic_release/oauth/v2.0/revoke HTTP/1.1\nHost: hello.mister-james.com\nContent-Type: application/x-www-form-urlencoded\ntoken=ACCESS_TOKEN_OR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\n\n ```\n\nOnce the token is successfully revoked, it can no longer be used to access the API or refresh any tokens. If you are revoking an `access_token`, the user will need to re-authenticate to obtain a new one.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"33242434","team":6456035,"collectionId":"3d2d1930-f69e-44e8-8bd1-26db6dd045a2","publishedId":"2sAXqqePBH","public":true,"publicUrl":"https://api.mister-james.com","privateUrl":"https://go.postman.co/documentation/33242434-3d2d1930-f69e-44e8-8bd1-26db6dd045a2","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"REST API for the Mister James CRM-System"},{"name":"title","value":"Mister James CRM-System: REST API"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/749d15af-cf0c-4e72-b540-8183b52fa533/bG9nb193aGl0ZS5wbmc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":"https://content.pstmn.io/02e67dbe-d51f-4dfa-94b3-c00f1c427ad3/bG9nby5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-09-18T15:31:21.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"Mister James CRM-System: REST API","description":"REST API for the Mister James CRM-System"},"logos":{"logoLight":"https://content.pstmn.io/02e67dbe-d51f-4dfa-94b3-c00f1c427ad3/bG9nby5wbmc=","logoDark":"https://content.pstmn.io/749d15af-cf0c-4e72-b540-8183b52fa533/bG9nb193aGl0ZS5wbmc="}},"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/e97d3a49741f90b5b3a7da623431f206da1aa95ae8a713e69579b2df61fea86f","favicon":"https://mister-james.com/favicon.ico"},"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://api.mister-james.com/view/metadata/2sAXqqePBH"}