Forms and events

Fetch form definitions and events, submit answers, and register event leads. Forms can return grading counts when questions have answer keys.

Access labels such as Origin + Brand key + Customer are defined in Headers and access. Each endpoint ends in a Try it console; set the host and keys once in its Settings tab or on the overview.

Create event lead

Method	URL path	Required access
POST	/api/v1/user/event/lead/:event_id	Origin + Brand key + Customer
POST	/api/v1/brand/event/lead/:event_id	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
path.event_id	number	yes	—
body.payload	object	optional	At least one of ("email" , "phone_number"); Paired fields ("phone_number" , "phone_prefix")
body.payload.first_name	string	optional	—
body.payload.last_name	string	optional	—
body.payload.email	string	optional	Email address
body.payload.phone_prefix	string	optional	—
body.payload.phone_number	string	optional	—
body.payload.source	string	optional	—
body.payload.push_token	string	optional	—
body.payload.form_responses	array of object	optional	Default ([ ])
body.payload.form_responses[].question_id	number	yes	—
body.payload.form_responses[].answer	any JSON value	yes	—

Example (first URL):

curl -X POST "$BASE_URL/api/v1/user/event/lead/1" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"email":"alex@example.com"}}'

Response: {"success":true,"message":"..."} from the event-lead service.

Source: app/v1/controller/event_controller.ts:12 → createEventLead; routes: routes/v1/event_route.ts:66; service: _createEventLead (app/v1/service/event_service.ts:14).

Get event by ID

Method	URL path	Required access
GET	/api/v1/brand/event/:event_id	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
path.event_id	number	yes	—

Example:

curl -X GET "$BASE_URL/api/v1/brand/event/1" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/event_controller.ts:77 → getEventById; routes: routes/v1/event_route.ts:75; service: _getEventById (app/v1/service/event_service.ts:177).

Get all events

Method	URL path	Required access
GET	/api/v1/brand/events	Origin + Brand key
GET	/api/v1/user/events	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
query.tags	array of string	optional	—
query.limit	number	optional	—
query.offset	number	optional	—
query.search	string	optional	Whitespace trimmed
query.group_by	array of string	optional	—
query.includeExpired	boolean	optional	Default (false)
query.expiredOnly	boolean	optional	—
query.type	string	optional	Allowed values ("standard", "drop")
query.sortItem	string	optional	No controller schema
query.sortType	string	optional	No controller schema

tags and group_by are comma-separated query strings. sortItem and sortType are comma-separated lists of equal length. includeExpired and expiredOnly are compared with the string true.

Example (first URL):

curl -X GET "$BASE_URL/api/v1/brand/events?limit=10&offset=0" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/event_controller.ts:110 → getAllEvents; routes: routes/v1/event_route.ts:94; service: _getAllEvents (app/v1/service/event_service.ts:227).

Create form response

Method	URL path	Required access
POST	/api/v1/brand/form/response	Origin + Brand key + Customer
POST	/api/v1/brand/public/form/response	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.form_assignment_id	number	yes	—
body.payload.form_response	array of object	yes	—
body.payload.form_response[].question_id	number	yes	—
body.payload.form_response[].answer	string	yes	Whitespace trimmed

Example (first URL):

curl -X POST "$BASE_URL/api/v1/brand/form/response" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"form_assignment_id":1,"form_response":[{"question_id":1,"answer":"example"}]}}'

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: message, id, correct_answer_count, total_questions.

Source: app/v1/controller/form_controller.ts:8 → createFormResponse; routes: routes/v1/form_route.ts:50; service: _createFormResponse (app/v1/service/form_service.ts:4).

Get form by type

Method	URL path	Required access
GET	/api/v1/brand/form/type	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
query.id	number	yes	—
query.type	string	yes	Whitespace trimmed; Allowed values ("scan_verify", "scan_survey", "product_review", "form_survey")

Example:

curl -X GET "$BASE_URL/api/v1/brand/form/type?id=1&type=scan_verify" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/form_controller.ts:55 → getFormByType; routes: routes/v1/form_route.ts:60; service: _getFormByType (app/v1/service/form_service.ts:111).

Related pages

• Batch Commerce API overview
• Implementation notes