API reference

Forms. 12 operations.

12 of them work. Each needs a bearer token with its scope. All operations.

Operations

POST/api/v1/forms/enquiries/{id}/notesforms.add-enquiry-noteforms.write

Parameters

`id`path	string
`id`path	string
`Idempotency-Key`header	stringSee common parameters

Request body

EnquiryNoteRequest

Answer

EnquiryChange

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/enquiries/{id}/notes

GET/api/v1/forms/enquiriesforms.enquiriesforms.read

Parameters

`status`query	stringOnly the enquiries of this status: new, answered, closed or spam; every status but spam when left out.
`after`query	integerThe id of the last enquiry of the page before; the first page when left out.
`limit`query	integerThe most enquiries in the page: 1 to 100; 50 when left out.

Answer

EnquiryList

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/enquiries

GET/api/v1/forms/enquiries/{id}forms.enquiryforms.read

Parameters

`id`path	string
`id`path	string

Answer

EnquiryDetail

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/enquiries/{id}

GET/api/v1/forms/enquiries/countsforms.enquiry-countsforms.read

Answer

EnquiryCounts

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/enquiries/counts

GET/api/v1/forms/formsforms.formsforms.read

Answer

array of FormSummary

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/forms

POST/api/v1/forms/submissions/{number}/readforms.mark-submission-readforms.write

Parameters

`number`path	string
`number`path	string
`Idempotency-Key`header	stringSee common parameters

Answer

ReadChange

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/submissions/{number}/read

POST/api/v1/forms/enquiries/{id}/statusforms.set-enquiry-statusforms.write

Parameters

`id`path	string
`id`path	string
`Idempotency-Key`header	stringSee common parameters

Request body

EnquiryStatusRequest

Answer

EnquiryChange

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/enquiries/{id}/status

POST/api/v1/forms/submissions/{number}/noteforms.set-submission-noteforms.write

Parameters

`number`path	string
`number`path	string
`Idempotency-Key`header	stringSee common parameters

Request body

SubmissionNoteRequest

Answer

SubmissionChange

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/submissions/{number}/note

POST/api/v1/forms/submissions/{number}/statusforms.set-submission-statusforms.write

Parameters

`number`path	string
`number`path	string
`Idempotency-Key`header	stringSee common parameters

Request body

SubmissionStatusRequest

Answer

SubmissionChange

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/submissions/{number}/status

GET/api/v1/forms/files/{id}forms.submission-fileforms.read

Parameters

`id`path	string
`id`path	string

Answer

SubmissionFile

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/files/{id}

GET/api/v1/forms/submissionsforms.submissionsforms.read

Read a page at a time: give limit (1 to 500; 100 when none is given) and after, the Next-Cursor of the page before. Follow the Link, rel next, to the rest.

Parameters

`form`query	stringOnly the submissions of this form (its name in store.yaml); every form when left out.
`status`query	stringOnly the submissions of this status: new or done; either when left out.
`limit`query	integerThe most submissions in the page: 1 to 500; 100 when the call gives no limit. The Next-Cursor and Link headers name the next page.
`after`query	stringSee common parameters

Answer

array of Submission

Errors: 400, 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/submissions

GET/api/v1/forms/submissions/unread-countforms.unread-countforms.read

Answer

UnreadCount

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/forms/submissions/unread-count

Schemas 19

Enquiry

Enquiry is an enquiry, as the store keeps it.

`at`required	string (date-time)
`email`required	string
`erased`required	boolean
`id`required	integer
`message`required	string
`name`required	string
`phone`required	string
`product_name`required	string
`product_slug`required	string
`quantity`required	integer
`sku`required	string
`status`required	EnquiryStatus
`verdict`required	string

EnquiryChange

EnquiryChange is what a change did: Changed is false when the enquiry stood as asked.

`changed`required	boolean
`status`required	EnquiryStatus

EnquiryCounts

EnquiryCounts are the enquiries by status, and when the oldest new one was made (nil when none is new): the Home attention line.

`answered`required	integer
`closed`required	integer
`new`required	integer
`oldest_new`	string (date-time)
`spam`required	integer

EnquiryDetail

EnquiryDetail is one enquiry with its notes, oldest first.

`enquiry`required	Enquiry
`notes`required	array of EnquiryNote

EnquiryList

EnquiryList is a page of enquiries and the counts of all of them. Next is the cursor of the page after, 0 for none.

`counts`required	EnquiryCounts
`items`required	array of Enquiry
`next`required	integer

EnquiryNote

EnquiryNote is a note the owner added to an enquiry.

`at`required	string (date-time)
`by`required	string
`id`required	integer
`text`required	string

EnquiryNoteRequest

EnquiryNoteRequest is a note to add: 1 to 2000 characters.

textrequired string

EnquiryStatus

EnquiryStatus is where an enquiry stands.

string

EnquiryStatusRequest

EnquiryStatusRequest is the status an enquiry is set to: answered, closed or spam. Setting spam suppresses the sender for further enquiries (ASI-6.8); an enquiry cannot be set back to new.

statusrequired EnquiryStatus

Field

Field is one field of a submission: its name, its label as store.yaml gives it now, and the value given.

`label`required	string
`name`required	string
`value`required	string

FormSummary

FormSummary is a form store.yaml defines, with how many submissions it holds (ASI POS and Mail F5).

`done`required	integer
`empty_text`	string
`name`required	string
`new`required	integer
`title`required	string

ReadChange

ReadChange is what a read mark did: whether it changed the item from unread to read for its actor.

changedrequired boolean

Submission

Submission is a form submission, as the store keeps it.

`at`required	string (date-time)
`done_at`	string (date-time)
`done_by`	string
`fields`required	array of Field
`files`	array of SubmissionFileRef
`form`required	string
`note`	string
`note_at`	string (date-time)
`note_by`	string
`number`required	integer
`read`required	boolean
`status`required	string
`title`required	string

SubmissionChange

SubmissionChange is what a call that changes a submission answers: whether it changed anything, and the submission as it then stands.

`changed`required	boolean
`submission`required	Submission

SubmissionFile

SubmissionFile is a file a submission carries as the engine kept it (F1): what names it, and its bytes, base64 in JSON.

`content_type`required	string
`data`required	string
`field`required	string
`id`required	string
`label`required	string
`name`required	string
`size`required	integer

SubmissionFileRef

SubmissionFileRef names a file a submission carries (F1): its id, which is also its address (GetSubmissionFile), the field it came through and that field's label, the name it is shown by (the client's, cleaned of any path and markup), its media type as the engine found it from its first bytes, and its size in bytes.

`content_type`required	string
`field`required	string
`id`required	string
`label`required	string
`name`required	string
`size`required	integer

SubmissionNoteRequest

SubmissionNoteRequest is the body of the call that sets the staff note of a submission: Note, "" to clear it.

noterequired string

SubmissionStatusRequest

SubmissionStatusRequest is the body of the call that marks a submission: Status is new or done.

statusrequired string

UnreadCount

UnreadCount is how many items the reader has not marked read.

unreadrequired integer

Made from engine/internal/openapi/openapi.json at commit 6c4cbd921. The contract-only operations come from the engine’s stub file, engine/internal/ops.