Custom Metadata

The MASV API allows Team admins to create and manage custom metadata forms on Portals. When a Portal has a form associated with it, a response to that form called “Form Data” is required before a Portal package can be created.

Note

MASV Agent automations do not support Portals with custom metadata forms because they require user interaction to fill out the form.

Delivery formats

Metadata can be delivered in file format and in package upload notification emails. The following delivery formats are supported:

• json
• csv
• xml
• email_body

Delivery formats are set on the form and multiple formats can be selected at a time. For file format deliverables, files are placed in the root of the relevant Portal package.

Custom metadata workflow

1. Team admin creates a form for a Portal.
2. Team admin updates the form to set form fields.
3. User creates a response to this form.
4. User creates a package, providing the form response in the create request.
5. User completes the upload flow.
6. When the user finalizes the package, the metadata is delivered.

Creating a form

Method	Route
POST	/v1/portals/{portal_id}/form

Headers

Name	Type	Required	Description
X-API-KEY	String	Yes	API key
Content-Type	String	Yes	Must be application/json

Body

Name	Type	Required	Description
name	String	Yes	Name of the form
delivery_formats	String[]	Yes	Array of delivery formats
form_template_id	String	No	ID of the form template this form was based on
fields	Field[]	No	Optional array of fields

Request

curl -d '{"name": "$FORM_NAME", "delivery_formats": ["csv", "xml"]}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/portals/$PORTAL_ID/form

Response

Returns 201 Created with the form object.

Form fields

Form fields have the following properties:

Property	Type	Description
name	String	Field name (must be unique per form, not shown to users)
label	String	Label shown to users
type	Enum	Input type: checkbox, radio, dropdown, date, short_text, long_text, number, url, email, package_name, package_description, sender_email
visibility	Enum	Visibility: required, optional, readonly, hidden
default_value	String	Default value
position	Integer	Render position (ascending order)
options	String[]	Options for checkbox, radio, dropdown types

Special field types

Fields of type package_name, package_description, and sender_email are used in the package creation process. There can only be one field of each type in a form.

Updating forms

Method	Route
PUT	/v1/metadata/forms/{form_id}

Headers

Name	Type	Required	Description
X-API-KEY	String	Yes	API key
Content-Type	String	Yes	Must be application/json

Body

Pass the full form object including modifications:

Name	Type	Description
name	String	The form’s name
delivery_formats	String[]	Delivery formats
disabled	Boolean	If true, the form is disabled
fields	FormField[]	Array of form fields

Caution

When a form’s fields are updated, the old fields are fully replaced.

Request

curl -d '{"name": "$NEW_NAME", "delivery_formats": ["json", "csv"], "disabled": false, "fields": [...]}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/metadata/forms/$FORM_ID

Submitting a form response

When submitting a form response, the only validation performed is on required fields. If a required field is missing a value, an error will be returned.

Method	Route
POST	/v1/portals/{portal_id}/form/responses

Headers

Name	Type	Required	Description
X-API-KEY	String	*	API key
X-Access-Code	String	*	The Portal’s access code
Content-Type	String	Yes	Must be application/json

Either X-API-KEY or X-Access-Code is required.

Body

A JSON object containing key/value pairs for each field. The key is the field’s name, the value is an object with a value property:

{
  "uploader_name": { "value": "Example uploader name" },
  "description": { "value": "Example package description" },
  "name": { "value": "Example package name" },
  "sender_email": { "value": "user@test.com" }
}

Request

curl -d '{"uploader_name": {"value": "Example name"}}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/portals/$PORTAL_ID/form/responses

Response

Returns 201 Created with the form response object including its id.

Using form responses

To attach a form response to a new Portal package, add the form response’s id to the create Portal package body under the key form_data_id. See Create a Portal package.

Getting package metadata

Method	Route
GET	/v1/packages/{package_id}/metadata

Headers

Name	Type	Required	Description
X-Package-Token	String	Yes	Full-access package JSON Web Token

Tip

To get a full-access package token, use the List Portal Packages endpoint with new=1, and use the resulting access_token.

Request

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
  -X GET https://api.massive.app/v1/packages/$PACKAGE_ID/metadata

Response

Returns 200 OK with the form response object including all field values.

Getting Portal metadata fields

To get the fields required to create a Portal form response, use the Get Portal endpoint. If it has a form requirement, an array of form fields will be returned under custom_metadata.

Method	Route
GET	/v1/portals/{portal_id}

Headers

Name	Type	Required	Description
X-API-KEY	String	*	API key
X-Access-Code	String	*	Portal’s access code

Either X-API-KEY or X-Access-Code is required.

Deleting forms

Method	Route
DELETE	/v1/metadata/forms/{form_id}

Request

curl -H "X-API-KEY: $API_KEY" \
  -X DELETE https://api.massive.app/v1/metadata/forms/$FORM_ID

Response

Returns 204 No Content.

Creating a form template

Method	Route
POST	/v1/teams/{team_id}/forms/templates

Body

Name	Type	Required	Description
name	String	Yes	Name of the form template
delivery_formats	String[]	Yes	Array of delivery formats

Request

curl -d '{"name": "$FORM_TEMPLATE_NAME", "delivery_formats": ["csv", "xml"]}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/forms/templates

Updating form templates

Method	Route
PUT	/v1/metadata/forms/templates/{form_template_id}

Same body format as updating forms.

Deleting form templates

Method	Route
DELETE	/v1/metadata/forms/templates/{form_template_id}

Request

curl -H "X-API-KEY: $API_KEY" \
  -X DELETE https://api.massive.app/v1/metadata/forms/templates/$FORM_TEMPLATE_ID

Response

Returns 204 No Content.