Columbus 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.
\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 as Administrator and issue tokens immediately.
\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
\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}
Tokens 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.
\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.
\nWeb applications can easily acquire an OAuth access token for any Columbus end user by following these steps:
\nredirect_uri URLs (HTTPS only)client_id and a client_secrethttps://marinus.app/oauth/authorize using the client_id and the redirect_uri parameters.client_id you received in step 1redirect_uri must be an HTTPS endpoint and has been set when you registered your application in step 1state parameter which will be included unchanged in the redirect.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.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:An example request:
\nPOST /oauth/access_token HTTP/1.1\nHOST: marinus.app\nContent-Type: application/x-www-form-urlencoded\n\nclient_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&redirect_uri=REDIRECT_URI\nAn example response:
\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\"}]}]\nclient_id - your application client id.client_secret - your application client secret.code - the OAuth verification code acquired via OAuth web authentication protocol.redirect_uri - the page to which your user will be redirected upon successfully authenticating.state - optional state to include in the redirect URI.grant_type - optional, if present must be authorization_codeBy default, a JSON dictionary and appropriate Content-Type response header is returned.
access_token - the OAuth access token for your user.keys - API keys per company granted accesspermissions - List of permissions allowed (CRUD, Create, Read, Update and Delete) per component for listed API keys of each companyOAuth 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.
\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.
All 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.
\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 with your requirements.
\nYou can find your monthly limit by looking at your Account Overview within your Columbus administrator dashboard
\nIf you are experiencing rate limiting errors, please wait 60 minutes to resume making API calls.
\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.
To reduce the amount of API calls, you can cache the request response.
\nIf the response consists of one more fields:
\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.
The 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:
\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.
A brief description of each end point is given below:
\nFetch all results of Companies Addresses object
\n","urlObject":{"path":["companies","addresses"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"ca875768-cb42-4aeb-85b9-fdcdc0494d0a","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"https://api.marinus.app/v1/companies/addresses"},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"bee979a5-519b-4526-b8cd-f5b6e7004250"},{"name":"/companies/addresses","id":"11edbe02-7186-4d16-b4c7-e461b1a292fb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Create new object of Companies Addresses
\n","urlObject":{"path":["companies","addresses"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"3014ba13-9eb8-428f-a3c1-3606bc445818","name":"OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Update existing object of Companies Addresses
\n","urlObject":{"path":["companies","addresses"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"6b3ac87e-5d1e-446d-b3d6-43c7bebebe5e","name":"OK","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"company_id\": \"Delete existing object of Companies Addresses
\n","urlObject":{"path":["companies","addresses"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"9affeac0-9657-4bb1-8f4b-8e5c9b8e777e","name":"OK","originalRequest":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"id\": \"Fetch single result of Companies Addresses object
\n","urlObject":{"path":["companies","addresses",":id"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[{"id":"478724e7-a7b5-4b75-89c1-67870e01cd75","description":{"content":"","type":"text/plain"},"type":"any","value":{"company_id":"Fetch all results of Companies Attachments object
\n","urlObject":{"path":["companies","attachments"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"a1a5b9b4-5e08-456d-af34-8441265e15e9","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"https://api.marinus.app/v1/companies/attachments"},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"fcbfdd53-9408-44c5-a0c3-7adcf380395a"},{"name":"/companies/attachments","id":"f2212d2b-b70d-4a3b-a175-b59cf1e7b4be","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Create new object of Companies Attachments
\n","urlObject":{"path":["companies","attachments"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"a0cf205e-78ea-40e4-afb2-9115ca30a714","name":"OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Update existing object of Companies Attachments
\n","urlObject":{"path":["companies","attachments"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"c744ed76-bb32-4ca9-8790-d501bbcf61c7","name":"OK","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"company_id\": \"Delete existing object of Companies Attachments
\n","urlObject":{"path":["companies","attachments"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"6f6dbbd8-509f-4409-85f8-5ed9e7328600","name":"OK","originalRequest":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"id\": \"Fetch single result of Companies Attachments object
\n","urlObject":{"path":["companies","attachments",":id"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[{"id":"11776f56-340b-408f-b551-802dd547760b","description":{"content":"","type":"text/plain"},"type":"any","value":{"company_id":"Fetch all results of Companies Branches object
\n","urlObject":{"path":["companies","branches"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"668c2ab0-8c36-430c-ad90-6c90dee7fabe","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"https://api.marinus.app/v1/companies/branches"},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"5b570e86-0625-4712-8c72-4fd7718ab20f"},{"name":"/companies/branches","id":"b7093d75-8d47-47fa-bed0-e103c568b2cf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Create new object of Companies Branches
\n","urlObject":{"path":["companies","branches"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"d0209b4c-446b-4bf8-bb6a-127205c356af","name":"OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Update existing object of Companies Branches
\n","urlObject":{"path":["companies","branches"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"3885fb26-e5b3-4bb7-ba56-1b8c8bd19b9e","name":"OK","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"company_id\": \"Delete existing object of Companies Branches
\n","urlObject":{"path":["companies","branches"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"d2d450e9-ee7b-4f7c-a8da-f5ec94bf3bee","name":"OK","originalRequest":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"id\": \"Fetch single result of Companies Branches object
\n","urlObject":{"path":["companies","branches",":id"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[{"id":"8b5d4a94-c22c-49c7-9745-fbe911a2b2db","description":{"content":"","type":"text/plain"},"type":"any","value":{"company_id":"Fetch all results of Companies Budgets object
\n","urlObject":{"path":["companies","budgets"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"f4cb1dc8-7e89-418e-bc25-7f90e9e83ffb","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"https://api.marinus.app/v1/companies/budgets"},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"2b0edf02-6666-43c9-a565-6eb176559aac"},{"name":"/companies/budgets","id":"45ce6656-d38c-4bd2-a47c-443fd99ac41c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Create new object of Companies Budgets
\n","urlObject":{"path":["companies","budgets"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"7e4145eb-5904-4cc6-8ba6-ef26f80ec411","name":"OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"Update existing object of Companies Budgets
\n","urlObject":{"path":["companies","budgets"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"26d7ce35-7def-4f12-ad48-0da7aff583c0","name":"OK","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"company_id\": \"Delete existing object of Companies Budgets
\n","urlObject":{"path":["companies","budgets"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"f724e17b-b15f-4d78-9bbc-82585140797a","name":"OK","originalRequest":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"id\": \"Fetch single result of Companies Budgets object
\n","urlObject":{"path":["companies","budgets",":id"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[{"id":"b6198426-17d6-4a76-b6c8-244c70467383","description":{"content":"","type":"text/plain"},"type":"any","value":{"company_id":"Fetch all results of Companies Catalogues Custom Items Alternatives object
\n","urlObject":{"path":["companies","catalogues","custom","items","alternatives"],"host":["https://api.marinus.app/v1"],"query":[],"variable":[]}},"response":[{"id":"f14e89b6-1deb-4ecc-8b39-57ff1d7078f8","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"https://api.marinus.app/v1/companies/catalogues/custom/items/alternatives"},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"d5e4e347-2b4b-4f0c-acef-0ce715f3cba1"},{"name":"/companies/catalogues/custom/items/alternatives","id":"76b8cff2-60fd-474c-bf92-b54c447d0ae8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": \"