APIs for Registration Form

This page covers the Public API for managing Registration Forms — the sign-up forms your wholesale customers submit. All 4 operations share the same base URL, headers, and authentication described in Public APIs.

Note

A Registration Form’s field layout (elements) can get complex. Before building a request from scratch, we recommend using GET on an existing form you built in the app to see a real example of the shape expected, then adjust only what you need.

Create a Registration Form

Endpoint

POST https://wholesale.samita.io/api/v1/registration-forms

Request Headers

Header	Description	Required
X-SAMITA-API-KEY	API key provided in the Wholesale app	Yes
X-SAMITA-SHOP-URL	Shopify shop domain in format xxx.myshopify.com	Yes
CONTENT-TYPE	Must be application/json	Yes

This API requires the Create permission on the API key.

Request Body

Top-level fields:

Field	Type	Required	Description
title	string	Recommended	The form’s name in the app.
status	boolean	Recommended	Whether the form is active.
shopify_integration	object	Yes	Controls how submissions connect to Shopify customers — see below.
elements	array	Yes	The form’s fields, in display order — see below.
header	object	No	Header text shown at the top of the form.
footer	object	No	Footer buttons and text shown at the bottom of the form.
general	object	No	Approval behavior and default customer tags.
errorMessage	object	No	Custom validation error text.
reCaptcha	object	No	Whether reCAPTCHA is required on this form.
afterSubmit	object	No	What happens after a customer submits.

shopify_integration

Field	Type	Notes
ifExist	string (required)	returnError, continueAndUpdate, or continueAndIgnoreError — what happens if a submitted email already has a customer account.
showMessage	boolean	Show a message pointing the customer to log in instead.
messageRedirectToLogin	string	Text for that message.
sendEmailInvite	boolean	Send Shopify’s account activation email.
acceptsMarketing	boolean	Opt the new customer into marketing emails.

elements (array of field objects)

Every element needs a type — common types include text, email, phone, password, number, name, url, checkbox, radio, country, datetime, file, hidden, heading, paragraph, devider, and html.

Field	Type	Applies to	Notes
type	string (required)	all	Element type.
columnWidth	number (required except devider)	all	33.33, 50, or 100.
label / placeholder / description	string	input types	Field labeling.
required	boolean (required for heading, paragraph, devider, html)	those types	Whether the field must be filled in.
hasConfirm, labelConfirm, placeholderConfirm, descriptionConfirm	—	password	Adds a confirm-password field.
options, defaultOptions, defaultOption, defaultSelected	—	checkbox, radio, country	Choice list configuration.
inlineOption	number (required)	checkbox, radio	20, 25, 33.33, 50, or 100.
heading / text	string	heading / paragraph	Display content.
html	string	html	Raw HTML block.
allowed-multiple	boolean	file	Allow multiple file uploads.
allowed-extension	array	file	Any of: csv, pdf, jpg, jpeg, gif, svg, png, psd, ai, stl, stp, step, doc, docx, txt, ex2, dxf, gbr, eps, mov, mp4, xls, xlsx, ods, numbers, xlsm, zip, heic, heif.
format, date-format, time-format	string	datetime	format: date/time/date-and-time. date-format: Y-m-d/d-m-Y/m-d-Y/d-m/m-d. time-format: 12h/24h.
integration	string	any	Maps this field to a Shopify customer property: email, phone, first_name, last_name, addresses.address1, addresses.address2, addresses.city, addresses.province, addresses.zip, addresses.company, addresses.country, password, tags[], or note[].

header, footer, general, errorMessage, reCaptcha, afterSubmit

Section	Field	Type	Notes
header	active	boolean	Show/hide the header.
header	title	string, max 255
header	description	string
footer	description	string
footer	previousText, nextText, submitText, resetButtonText	string	Button labels.
footer	resetButton, submitFullWidth	boolean
footer	submitAlignment	string	left, center, or right.
general	customerTaxExempt	boolean
general	customerProcess	string	review-approving (manual approval) or approving (automatic).
general	customerTags	array	Tags applied to approved customers.
errorMessage	required, invalidName, invalidEmail, invalidURL, invalidPhone, invalidNumber, invalidPassword, confirmPasswordNotMatch, customerAlreadyExists, fileSizeLimit, fileNotAllowed, requiredCaptcha, shopifyInvalidPhone, shopifyPhoneHasAlready, shopifyInvalidProvice, otherError	string	Custom text per validation error.
reCaptcha	enable	boolean
afterSubmit	action	string	clearForm, redirectToPage, or hideForm.
afterSubmit	message, redirectUrl	string

Response

200 – Success returns the created record. See the example under Get a Registration Form below for the response shape.

Update a Registration Form

PUT https://wholesale.samita.io/api/v1/registration-forms/{id}

Same headers as Create. Only send the fields you want to change — title, status, and secret_configs (the full config object, in the same shape returned by GET, under the key configs) are all optional. Unspecified fields keep their current value. This API requires the Update permission.

Get a Registration Form

GET https://wholesale.samita.io/api/v1/registration-forms/{id}

Same headers as Create, no request body. This API requires the View permission.

200 – Success example:

{
  "id": 1,
  "title": "Wholesale Registration",
  "status": true,
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00",
  "configs": {
    "header": {
      "active": true,
      "title": "Apply for a wholesale account",
      "description": ""
    },
    "footer": {
      "previousText": "Back",
      "nextText": "Next",
      "submitText": "Submit",
      "resetButton": false,
      "resetButtonText": "Reset",
      "submitFullWidth": false,
      "submitAlignment": "left"
    },
    "general": {
      "customerTaxExempt": false,
      "customerProcess": "review-approving",
      "customerTags": ["wholesale"]
    },
    "reCaptcha": {
      "enable": false
    },
    "afterSubmit": {
      "action": "clearForm",
      "message": "Thanks! We'll review your application shortly.",
      "redirectUrl": ""
    },
    "integration": {
      "shopify": {
        "ifExist": "returnError",
        "showMessage": true,
        "sendEmailInvite": true,
        "acceptsMarketing": false,
        "integrationElements": {
          "email": "email",
          "first_name": "first_name",
          "last_name": "last_name"
        }
      }
    },
    "elements": [
      { "id": "first_name", "type": "name", "label": "First name", "required": true, "columnWidth": 50 },
      { "id": "last_name", "type": "name", "label": "Last name", "required": true, "columnWidth": 50 },
      { "id": "email", "type": "email", "label": "Email", "required": true, "columnWidth": 100 }
    ]
  }
}

Delete a Registration Form

DELETE https://wholesale.samita.io/api/v1/registration-forms/{id}

Same headers as Create. Pass an ids parameter — a comma-separated list of form IDs to delete (as a query string parameter or a JSON body field), e.g. ids=1,2,3. This API requires the Delete permission.

200 – Success:

{
  "success": true
}

Error responses

All 4 endpoints share the same error responses as the rest of the Public API — see Public APIs for 401 Unauthorized, 403 Forbidden, and 429 Too Many Requests.