{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"3a1e2534-ce6e-452a-8fad-bbbd825b1dfb","name":"Columbus API v1","description":"# Welcome to Columbus API Documentation\n\nColumbus is a cloud-based supply chain management tool for the maritime industry. The platform is powerful and versatile, allowing you to create dynamic integrations with Columbus with ease.\n\n\n# Introduction\n\nIf you are interested in integrating your app or software platform with Columbus, you'll need to register and authenticate your service with our API. If you have a Premium or a Enterprise account, you can login to [your account](https://marinus.app/administrator/api/tokens) as Administrator and issue tokens immediately.\n\nIf you don't have a Premium or Enterprise account and want to integrate with our platform, you can sign up for a Developer Account [here](https://marinus.dev/register)\n\n## Authentication\n\nColumbus only supports OAuth2 with TLS. This requires your endpoint to have a valid SSL certificate installed.\nAPI requests should be made using the OAuth Bearer Token specification, using the Authorization header in the request.\nHere is an example:  `Authorization: Bearer {token}`\n\nTokens are valid for the duration you have set and up to a maximum of 1 year after issue.\nIf your Columbus account was previously marked as Premium or Enterprise and has been downgraded to Standard, the tokens will be invalidated and you will need to upgrade your account and issue new tokens.\n\nIf you have an Developer Account, your tokens will only be valid for 90 days after issue. After which you must issue a new token if you wish to continue using Columbus.\n\n## OAuth Web Flow\n\nWeb applications can easily acquire an OAuth access token for any Columbus end user by following these steps:\n\n 1. Register your application\n\t 1. You will need to set an application name, description and logo\n\t 2. You will need to set the authorised `redirect_uri` URLs (HTTPS only)\n\t 3. You will be assigned a `client_id` and a `client_secret`\n 2. Redirect your user to `https://marinus.app/oauth/authorize` using the `client_id` and the `redirect_uri` parameters.\n\t 1. The `client_id` you received in step 1\n\t 2. The  `redirect_uri` must be an HTTPS endpoint and has been set when you registered your application in step 1\n 3. You can also pass an optional `state` parameter which will be included unchanged in the redirect.\n 4. Once your application has been authorised, your user will be directed to the page specified in the `redirect_uri` parameter. Columbus will automatically append a code parameter to this endpoint URI that contains a value that can be exchanged for an OAuth access token using the `oauth/access_token` endpoint in point 5.\n 5. Use the `oauth/access_token` API endpoint to acquire an OAuth access token, passing the `code` value appended by Columbus to the previous redirect and the same `redirect_uri` value that was previously used. This API endpoint will return the following:\n\t 1. OAuth Token\n\t 2. A list of API keys per company\n\t 3. A list of permissions allowed\n\n**An example request:**\n\n    POST /oauth/access_token HTTP/1.1\n    HOST: marinus.app\n    Content-Type: application/x-www-form-urlencoded\n    \n    client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&redirect_uri=REDIRECT_URI\n\nAn example response:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/x-www-form-urlencoded\nContent-Length: 219\n\naccess_token=TOKEN&keys=[{\"marinus-global-limited\": \"KyMf0jV4ZV\"},{\"marinus-other-company\": \"JMhnUHiLaS\"}]&permissions=[{\"purchasing\": [{\"requisition\": \"crud\"}, {\"rfq\": \"r\"},{\"purchase-order\": \"r\"},{\"invoice\": \"cru\"}]}]\n```\n### Parameters for OAuth Web Flow\n\n-  `client_id`  - your application client id.\n-  `client_secret`  - your application client secret.\n-  `code`  - the OAuth verification code acquired via OAuth web authentication protocol.\n-  `redirect_uri`  - the page to which your user will be redirected upon successfully authenticating.\n-  `state`  - optional state to include in the redirect URI.\n-  `grant_type`  - optional, if present must be  `authorization_code`\n\n### Response Value\n\nBy default, a JSON dictionary and appropriate  `Content-Type`  response header is returned.\n\n-  `access_token`  - the OAuth access token for your user.\n-  `keys`  - API keys per company granted access\n-  `permissions` - List of permissions allowed (CRUD, Create, Read, Update and Delete) per component for listed API keys of each company\n\n# Best Practices\n\n\n## OAuth Token / API Key Security\n\nOAuth access tokens and API keys must be **treated as secret data** and not exposed to any users. To ensure the security of your OAuth access token or API key, **we strongly recommend** that you make requests to the Columbus API server-side.\n\nAny requests to the Columbus API made via client-side JavaScript present the risk of your OAuth token or API key being compromised and subsequently your account will be terminated immediately. Never include your `api_key` or `access_token` inline on the page. Don't keep any references to your `api_key` or `access_token` in code that is contained in external javascript files which are included in the page. For additional security, don't have the key or token itself contained anywhere in your JavaScript code, but rather make an ajax call to load it, and keep it in a variable stored in a privately scoped method.\n\n## URL Encoding\n\nAll long URLs sent to the Columbus API must be URL encoded, even if these links already contain escaped characters. For more information about URL encoding, see this  [Wikipedia article](https://en.wikipedia.org/wiki/Percent-encoding).\n\n## Rate Limiting\n\nColumbus enforces per-month, per-hour, per-minute, and per-IP rate limits for each API method, and limits API users to a maximum of five concurrent connections from a single IP address. Our default limits are more than sufficient for nearly all use cases. Please read through this documentation in its entirety to avoid common causes of rate limiting issues. If you would like to increase your rate limits, please  [contact us](mailto:support@marinus.io) with your requirements. \n\nYou can find your monthly limit by looking at your Account Overview within your Columbus administrator dashboard\n\n-   1,000 calls per hour\n-   100 calls per minute\n\nIf you are experiencing rate limiting errors, please wait 60 minutes to resume making API calls.\n\n\n## Timestamps\n\nThe API uses the following format for timestamps:  `[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]±hhmm`. Another Example would be:  `2019-07-09T11:02:03-0300`.\n\n\n## Cache\n\nTo reduce the amount of API calls, you can cache the request response. \n\n## Personally Identifiable Information (PII)\nIf the response consists of one more fields:\n- Full name\n- Home address\n- Email address\n- Social security number\n- Passport number\n- Driver’s license number\n- Credit card numbers\n- Date of birth\n- Telephone number\n- Gender\n- Race\n- Age\n- Religion\n\nYou will be responsible for sensible and secure storage of the details above.\nIf you are concerned about PII, you can specify in your application settings to **anonymise** the PII details in each request. The fields identified as PII will be marked with the value `anonymised`.\n\n# Restfulness\n\nThe Columbus API follows the standard REST convention of utilising the HTTP response codes to identify the status of the response. These include, but are not limited to:\n\n -   **200 - SUCCESS**\n -   **400 - INVALID**\n -   **403 - FORBIDDEN**\n -   **404 - NOT FOUND**\n -   **500 - INTERNAL ERROR**\n\n---\n\n - **GET** requests will return data \n - **POST** requests are for creation \n - **PUT** requests are for updates \n - **DELETE** requests are for removal\n\n# Collections\n\n## Data\nThe Data collections API endpoints contains all the public available data points used within Columbus. These endpoints only contain `GET` methods to retrieve all objects or a single object with a given `id`.\n\nA brief description of each end point is given below:\n\n- **associations** (companies associated organisations, such as IMPA, ISSA)\n- **catalogue** (catalogue specific products, attributes, images, categories and brands)\n- **catalogues** (available catalogues) \n- **certifications** (shipping crew certifications) \n- **countries** (country specific provinces, cities and ports)\n- **crm** (CRM lead types, statuses, categories and stages)\n- **currencies** (currencies list with symbol, iso3 format and full name)\n- **delivery** (delivery conditions for each Requisition)\n- **identification** (identification conditions for each Requisition)\n- **insurances**  (general list of available insurance types)\n- **inventory**  (general list of inventory reasons)\n- **job**  (general list of buyer and supplier job titles)\n- **leave**  (general list of leave/holiday types)\n- **locales** (general list of all locales in the world)\n- **services** (general list of available services of suppliers)\n- **ships**  (ship specific information, capacity, engine type, flags, managers, crew list)\n- **sic** (Standard industrial classification of economic activities (SIC))\n- **timezones** (all the time zones available with name and time)\n- **transport**   (transport conditions for each Requisition)\n- **unit** (general list of available unit of measurements, imperial and metric system, single and plural)\n- **users** (general list of available permissions within the platform)\n\n## Companies\n- **companies** (Available companies under the given API key)\n- **addresses** (Company linked addresses)\n- **attachments** (Files for uploaded content under a company)\n- **branches** (List of branches but not assigned yet)  \n- **budgets** ( Budgets set per period, with amount, date start/end and currency )  \n- **catalogues** (Company specific catalogues )  \n- **contracts** (Company specific contracts, Payment, Delivery, Warranty)  \n- **crm** (Company specific CRM leads, opportunities and contacts)  \n- **flows** (Company specific flows, Approval and Work flows)  \n- **on** (Many to Many relationships with Company object)  \n- **orders** (Company Orders, Items, Attachments, Reviews, Suppliers)  \n- **ships** (Company specific ships, logs, crew list and tracking)  \n- **subscriptions** (Company specific subscriptions on Columbus)  \n- **suppliers** (Company specific supplier groups and preferred suppliers)  \n- **tasks** (Company and User specific tasks)  \n- **warehouses** (Company specific warehouses, locations and inventory)\n\n## Users\n- **users** (Users information)\n- **on** (One to Many and Many to many User linked information)  \n- **permissions** (User permissions on given roles)  \n- **roles** (User roles per Account)  \n- **settings** (User specific account settings)  \n- **signatures** (User encrypted signatures)  \n- **teams** (Company created Teams for Users)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"7958518","team":417053,"collectionId":"3a1e2534-ce6e-452a-8fad-bbbd825b1dfb","publishedId":"SVSNK7r3","public":true,"publicUrl":"https://api.developers.marinus.app","privateUrl":"https://go.postman.co/documentation/7958518-3a1e2534-ce6e-452a-8fad-bbbd825b1dfb","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","version":"8.10.1","publishDate":"2019-07-21T00:32:27.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/e2440ebba00b63173916d88072850d29c7c01354244330cda90de31374678101","favicon":"https://res.cloudinary.com/postman/image/upload/v1561592849/team/n1jjlokxpetwtjrzypgi.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.developers.marinus.app/view/metadata/SVSNK7r3"}