POST /api/:space/events

Description:

Load a set of events to the CompetitionLabs database.

CompetitionLabs works with UTC timestamps, hence the field - "tranasctionTimestamp" which is the time from your system will be converted to UTC and stored in our backend systems.

We expect a POST request to be in the form of an array of event. An array can contain a maximum of 10,000 events in one request. Note that you can send multiple concurrent requests with up to 10,000 events at the same moment in time.

It is worth noting that the post and notify pattern is as much for fail-over, resilience and, running in parallel as it is for straight feeding the events engine

Sending an Event with a memberRefId that does not exist in the system the Member is automatically created within your space

Sending an Event with a entityRefId that does not exist in the system the Product is automatically created within your space

Resource URL:

https://<apphost>.competitionlabs.com/api/<your-space>/events

Request header

Key	Value	Required
X-API-KEY	Your unique API key	Yes
Content-Type	application/json	Yes

Request URL parameter

Parameter	Type	Required	Description
space	String	Yes	This is the space name which is linked to the account

Post body parameters

Parameter	Type	Required	Description
memberId	String	Optional	A unique identifier of a member. Can be sent memberId or MemberRefId
memberRefId	String	Yes	A unique identifier of a member. Can be sent memberId or MemberRefId
action	String	Yes	The identifier that describes the meaning of this event.
batchId	String	Optional	The batch identifier is used to group related event stream data together.
entityId	String	Optional	It is a reference to a Product models ID.
entityRefId	String	Yes	It is a reference Id of a Product model.
sourceValue	Double	Yes	The actual numerical value related to the event.
points	Double	Optional	A value derived from the source value field.
transactionTimestamp	DateTime	Yes	The time at which this event happened. ISO8601 timestamp.
relatesTo	Sequence [String]	Optional	Contains relatable object Id's of type of Competitions or Contests.
relatesToExternal	Sequence [String]	Optional	Are meant to record extra information about the object that can be the original transaction Id or extra tagging information.
metadata	Object	Optional	A list of MetaData. An object of key value pair (KVP):
			Parameter	Type	Required	Description
			key	String	Yes	Is a unique identifier
			value	Any	Yes	The data that is identified.

EXAMPLE

Request

curl
    --header "X-API-KEY: <your-api-key>"
    --header "Content-Type: application/json"
    --request POST https://app.competitionlabs.com/api/<your-space-name>/events
    -d '[{"sourceValue": 3.5, "memberRefId": "uzHL1GwBY7sgiVmDHkkF", "entityRefId": "fruits", "action": "win", "transactionTimestamp": "2019-08-30T09:11:00.827+00:00", "metadata": {"realMoneyAmount": 10, "bonusAmount": [0.0]}}]'

Response

Status: 200 OK

Request Multiple Event sample POST body

[{
	"sourceValue": 3.5,
	"memberRefId": "uzHL1GwBY7sgiVmDHkkF",
	"entityRefId": "fruits",
	"action": "win",
	"transactionTimestamp": "2019-08-30T09:11:00.827+00:00",
	"metadata": {
			"realMoneyAmount": 10,
			"bonusAmount": [0.0]
	}
},
{
	"sourceValue": 4,
	"memberRefId": "uzHL1GwBY7sgiVmDHkkF",
	"entityRefId": "fruits",
	"action": "bet",
	"transactionTimestamp": "2019-08-30T09:11:00.827+00:00"
	"metadata":{
        	"test2-for":10
        }
}]

Response Multiple Event sample of POST body

Status: 200 OK

ERROR CODES

Code	HTTP Status	Description	Example
	503	`Action` parameter was excluded; `TransactionTimeStamp` parameter was excluded or empty;	Error Response 503 Expand source { "status": 503 }
1008	406	`Product reference id` parameter was excluded; `Member reference id` is empty or parameter was excluded;	Error Response 406 Expand source { "errors": [ { "message": "Product reference id is empty for query with account id 0sn4DmUBkPH_lz9GgxBM", "code": 1008, "status": 406 } ] } Error Response 406 Expand source { "errors": [ { "message": "Member reference id is empty for query with account id 0sn4DmUBkPH_lz9GgxBM", "code": 1008, "status": 406 } ] }
1006	404	`Action` was empty;	Error Response 404 and 406 Expand source { "errors": [ { "message": "1 event/s created successfully. Other events failed with errors.", "code": 1006, "status": 406, "children": [ { "message": "Please enter an action for the event.", "code": 1002, "status": 404 } ] } ] }
1002	406	`Action` was empty;
1002	404	`Product reference id` was empty;	Error Response 404 and 406 Expand source { "errors": [ { "message": "Please enter a name for the product.", "code": 1002, "status": 404 }, { "message": "The length of the Product Reference Id is invalid, 0. Valid length is greater than 3 and less than 200 characters", "code": 1003, "status": 406 } ] }
1003	406	`Product reference id` was empty;
	404	Modifying the Resource URL parameters that are mandatory	Error Response 404 Expand source { "status": 404 }