Create

The create method adds a new record to the collection.

Configuration Example

# spec.yml
name: Collection Name
methods:
  create:
    fields:
      - email
      - firstName
      - lastName
    requiredFields:
      - email
    excludedFields:
      - id
    parametersSchema:
      type: object
      properties:
        sendWelcomeEmail:
          type: boolean
          default: true

Properties:

fields (array): Whitelist of fields to include
requiredFields (array): Fields that must be provided
excludedFields (array): Fields to exclude from creation

Implementation Examples

REST API Mapping Implementation (Recommended)

File: create.rest.yml

path: /contacts
method: POST
requestMapping:
  data:
    email: { $var: $.fields.email }
    first_name: { $var: $.fields.firstName }
    last_name: { $var: $.fields.lastName }
    phone: { $var: $.fields.phone }
    send_welcome_email: { $var: $.parameters.sendWelcomeEmail }
responseMapping:
  id: { $string: { $var: response.data.contact_id } }

Operation Mapping Implementation

File: create.yml

implementationType: operation-mapping
mapping:
  operationKey: createContact
  inputMapping:
    contactData: { $var: $.fields }
    options:
      sendWelcomeEmail: { $var: $.parameters.sendWelcomeEmail }
  outputMapping:
    id: { $string: { $var: result.contactId } }

JavaScript Implementation

File: create.js

export default async function create({ apiClient, fields, parameters }) {
  const requestBody = {
    email: fields.email,
    first_name: fields.firstName,
    last_name: fields.lastName,
    phone: fields.phone,
    send_welcome_email: parameters?.sendWelcomeEmail || false,
  }

  const response = await apiClient.post("/contacts", requestBody)

  return {
    id: String(response.data.contact_id),
  }
}

Input

Property	Type	Description
`fields`	object	Record fields in API format (after fieldsToApi)
`credentials`	object	Authentication credentials
`parameters`	object	Method-specific parameters

Return Value

Property	Type	Description
`id`	string	The ID of the created record