All endpoints in this API require authentication to be accessed.
\nAuthentication is HMAC-signature based (we support both SHA1 and SHA256). Upon registering as a partner with Colossus Bets, you'll receive an api_auth_key and an api_auth_secret.\nPlease follow the steps below to sign your requests.
These headers have to be provided in all your requests:
\nDate: this is the HTTP timestamp of the request in the RFC 1123/2822 Internet Standard. For security reasons, our API will reject the request when the HTTP timestamp is too far in the past (currently set to 15 minutes max).\nExample: \"Mon, 23 Jan 1984 03:29:56 GMT\"
\nAuthorization: this is the header that will contain the HMAC signature. The format will be \"APIAuth {{api_auth_key}}:{{signature}}\". You'll need to substitute api_auth_key and signature. The former will be provided by us while the latter will need to be calculated (see below in Signature Generation paragraph).
(Optional) Content-MD5: this is the standard header which is the Base64 encoding of the MD5 hash of the request body. It's optional in case of an empty body or a GET request.
\n(Optional) Content-Type: this is the standard header which will tell the API how to read the request body. It's optional in case of an empty body or a GET request.
\nIn order to calculate the signature, you'll first need to generate the canonical string. The format for it is the following:
{{HTTP_METHOD}},[Content-Type],[Content-MD5],{{RequestURI}},{{Date}}
\npath part of your request URL, including the querystring parameters.The elements between {{ }} are mandatory, while the ones between [ ] are optional. All commas are mandatory, even when an element is missing.
Once you calculated the canonical string based on the request, you can proceed calculating the signature from it. This can be achieved with the following 2 steps:
\napi_auth_secret (provided by us).We'll now guide you through an example for a request authentication.
\nLet's assume Colossus Bets provided you with the following details:
\nLet's assume we want to call the POST /tickets endpoint to place a bet. We will have the following canonical string:
\nPOST,application/json,rY5GyingAbnOReyXXtSqyA==,/tickets,Tue, 11 Apr 2017 16:05:42 GMT
From which we can calculate the Base64 encoding of the SHA1 HMAC hash, using our api_auth_secret, is QZDwWjZOGKCe+DSVWwAQGhKySQ0=.
The final Authorization header will then be:
APIAuth api_auth_key:QZDwWjZOGKCe+DSVWwAQGhKySQ0= or \nAPIAuth-HMAC-SHA256 api_auth_key:QZDwWjZOGKCe+DSVWwAQGhKySQ0=
Returns a list of pools that are open for betting.
\nParameters:
\ncurrency optional (recommended), STRING, 3 letter ISO 4217, returns stake_sizes and fx_rates for the requested currency onlyincludes optional, STRING, default: includes=legs.sport_event, comma separated list of VALUE(.NESTED_VALUE)*, used for speeding up the request if not all pool information is neededincludes= left empty will return pool with basic dataReturns a summary list of pools that are 'recommended' for a particular customer type.
\nParameters:
\ncustomer_type required, INT, representing the type of customer (use 1 if unknown)num_pools required, INT, representing the number of pools to return, maximum 5currency optional (recommended), STRING, 3 letter ISO 4217, returns stake_sizes and fx_rates for the requested currency onlyReturns data for a widget to show live pool prizes.
\nParameters:
\nnum_pools required, INT, the number of pools to showReturns statistics for competitors (e.g. teams, horses, tennis players) within a specific pool.
\nParameters: None
\n","urlObject":{"path":["pools","{{pool_id}}","stats"],"host":["{{api_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"7a344548-38a2-7c76-b7d2-826268df1c95"},{"name":"Pool","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["var ApiAuth = eval(globals.loadApiAuth);","ApiAuth.computeSignature();"]}},{"listen":"test","script":{"type":"text/javascript","exec":["data = JSON.parse(responseBody);","var ToteTests = eval(globals.loadToteTests);","","ToteTests.checkPoolSerializer(data);"]}}],"id":"ab7d8fae-c415-2728-29ab-6676b099e9aa","request":{"method":"GET","header":[{"key":"Authorization","value":"{{api_auth_sha}} {{api_auth_key}}:{{signature}}"},{"key":"Date","value":"{{time}}"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Content-MD5","value":"{{content-MD5}}"}],"body":{"mode":"raw","raw":""},"url":"{{api_url}}/pools/{{pool_id}}","description":"Parameters:
\nincludes optional (recommended - empty), STRING, default: includes=prizes,fx_rates,smart_pick_perms,history.sport_event_history,legs.sport_event.competitors,sport_event.sport_event_competitors,legs.sport_event.venue,legs.sport_event.history,legs.sport_event.sport_code_sub_code,legs.sport_event.selections.unit_distributions, comma separated list of VALUE(.NESTED_VALUE)*, used for speeding up the request if not all pool information is neededincludes= left empty will return pool without the nested elementsParameters:
\ncurrency optional (recommended), STRING, 3 letter ISO 4217, returns stake_sizes and fx_rates for the requested currency onlyincludes optional (recommended - empty), STRING, default: includes=legs.sport_event, comma separated list of VALUE(.NESTED_VALUE)*, used for speeding up the request if not all pool information is neededincludes= left empty will return pool without the nested elementsungrouped optional, BOOLEAN, default: falseungrouped=true generates an array of poolsungrouped=false generates a nested list of arraysfilters optional, HASH (key value pair), default: {}, flags for the pools - ungrouped must be true to use it.sport_codes optional, array of STRING (see full list of SPORT_CODES at end of API document)type_codes optional, STRING, array of STRINGs (see full list of TYPE_CODES at end of API document)leg_nums optional, array of INTstatuses optional, array of STRINGsids optional, array of INTstart_date optionalend_date optionalEvery bet in the system goes into a specific pool. Pools can be single-leg or multi-leg, and can be of any sport type.
\nThe endpoints in this section are used for returning a list of pools, and full details of each pool, and for confirming settlement details.
\nKey endpoints are:
\nReturns the list of syndicates.\nParameters:
\ncustomer_id required, STRING, the user idcurrency required, STRING, 3 letter ISO 4217per optional, INT, number of syndicate to display, for pagination purposes. Default: 25page optional, page number in the list of syndicate, for pagination purposes. Default: 1search deprecated, moved to filterspool_id deprected, moved to filterssort_by optional, comma separated list of attributes (starting_soon, percentage_filled, contributors, cost)filters optional, HASH of attiributes to restrict the list of syndicatessearch optional, STRING to search forpool_id int, filter to have all the syndicates for a specific poolpool_type optional, comma separated list of SPORT_CODE.TYPE_CODE values (see list at end of API docs)almost_full optional, BOOLEAN, to see only the syndicates which are close to be fullstarting_soon optional, BOOLEAN, to see only the syndicates where the first leg is near to startfully_funded optional, OPTIONAL, to see only the fully funded syndicates (only true or nothing, false is ignored)incomplete optional, BOOLEAN, to see only the fully funded syndicates (only true or nothing, false is ignored)my_captains optional, only syndicates made by manager followed by tyhe usermanagers optional, array of managersReturns full details of a specific Syndicate.
\nParameters:
\nsyndicate_id required, INT, the id of the syndicatecurrency required, STRING, 3 letter ISO 4217, the currency used by the userReturns details of a manager.
\nParameters:
\nmanager_id required, INT, id of the manager to be displayedReturns best performing Syndicate managers.
\nUnder development.
\n","urlObject":{"path":["managers","leaderboard.json"],"host":["{{api_url}}"],"query":[{"key":"period","value":"1"}],"variable":[]}},"response":[],"_postman_id":"0ccddaf8-7e23-8407-87d1-9ab96e3965fb"},{"name":"Managers rank periods","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["var CB = eval(globals.loadColossus);","CB.computeSignature(['manager_id']);"]}},{"listen":"test","script":{"type":"text/javascript","exec":["data = JSON.parse(responseBody);","var CB = eval(globals.loadColossus);","","CB.checkManagerSerializer(data[0]);"]}}],"id":"7db42deb-6480-7db5-5a0b-33ce8f38fae7","request":{"method":"GET","header":[{"key":"Authorization","value":"{{api_auth_sha}} {{api_auth_key}}:{{signature}}"},{"key":"Date","value":"{{time}}"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Content-MD5","value":"{{content-MD5}}"}],"body":{"mode":"raw","raw":"{\n\"type_code\": \"RACE_WIN\",\n\"sport_code\": \"HORSE_RACING\",\n\"pool_id\": \"123456\",\n\"amount\": \"1\",\n\"currency\": \"CAD\",\n\"legs\": [\n {\n \"selections\": \"1/2/3/4/5/6/7/8/9/10\",\n \"scheduled_start\": \"2016-10-08T11:06:12.000Z\",\n \"leg_number\": 1\n },\n {\n \"selections\": \"1/2/3/4/5/6/7\",\n \"scheduled_start\": \"2016-10-08T11:40:12.000Z\",\n \"leg_number\": 2\n },\n {\n \"selections\": \"1/2/3/4/5/6/7\",\n \"scheduled_start\": \"2016-10-08T12:10:12.000Z\",\n \"leg_number\": 3\n },\n {\n \"selections\": \"1/2/3/4/5/6/7/8/9/10\",\n \"scheduled_start\": \"2016-10-08T18:12:12.000Z\",\n \"leg_number\": 4\n }],\n\"info\":\n{\n \"track_name\": \"Woodbine (SB)\",\n \"race_number\": \"13\"\n},\n\"prizes\": [\n { \n \"amount\": \"14000\",\n \"prize_code\":\"WIN\"\n }]\n}\n\n"},"url":"{{api_url}}/managers/rank_periods","description":"Returns the options for the time periods for the Leaderboard rankings.
\nUnder development.
\n","urlObject":{"path":["managers","rank_periods"],"host":["{{api_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"7db42deb-6480-7db5-5a0b-33ce8f38fae7"}],"id":"70084bb0-a94c-0f7b-dbf8-59020e99f80c","description":"Syndicates is a unique feature that lets customers from any partner site, in any language and currency, start a Syndicate to give themselves more chances to win. They can do this completely anonymously, or choose to share their Twitter handle to engage other users.
\nIf a user selects lots of different selections, thereby creating many lines, it can give them more chances to win. However it also becomes expensive. A Syndicate lets them buy a fraction of a ticket, and then other users can also buy portions of the ticket until it's fully bought. This gives all the users more chances to win, however they will also share that prize with the other users in the Syndicate.
\n","event":[{"listen":"prerequest","script":{"id":"a9d89bbf-ebe8-4352-bb52-ce91ca4894b3","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"28caeac2-27fb-4c2d-869e-19ada5456527","type":"text/javascript","exec":[""]}}],"_postman_id":"70084bb0-a94c-0f7b-dbf8-59020e99f80c"},{"name":"4. Receiving Updates","item":[],"id":"c8a49705-cafb-2943-4ddb-3a4212ab9969","description":"The API provides Callbacks for any updates to data. The Callback consists of a single endpoint which the Colossus API calls via POST to provide a summary of the new information available.
\nTo use the Callback, we require access to a single endpoint over HTTPS, which sens a JSON object via POST with the following parameters:
\nThis section contains a list of codes used in the API.
\nAPI usual request success responses:
\n200 ok for GET, DELETE, PUT, POST(rarely) requests201 created forPOST requestsAPI usual request client error responses: (some of them are accompanied by a readable error message)
\n400 bad request absent or invalid parameters401 unauthorized APIauth authentication failed or wrong merchant credentials403 forbidden accessing unauthorised resources404 not found missing records or files or wrong identifiers being passed406 not acceptable requests in invalid format (e.g. not json)422 unprocessable entity parameters fail more complex validation logicAPI unusual server request error responses:
\n500 internal server error usually unhandled parameters case, please let us know503 service_unavailable should not really happen, but some server probably down, please let us know504 getaway_timeout should not really happen, request took too long, please let us know, especially for 'finiancial' requests