Collection Record Management Guide

To create and update the records, follow these steps:

Fetch Collection Columns:
Before updating a record, it's essential to fetch the collection columns to determine the name of the columns and other informations. This step ensures you have the necessary information to update the record effectively

Example Response:

[
"columns": {
 "all": [
   {
     "id": "01HWQ7CW7T626WY2A3KV603ZNF_0_name_text",
     "type": "ap://system/datatype/text",
     "displayName": "Name"
   },
   {
     "id": "01HWQ7CW7T626WY2A3KV603ZNF_0_lcity_text",
     "type": "ap://system/datatype/text",
     "displayName": "Location-city",
     "references": {
       "primary": true,
       "entityType": "collection",
       "entityId": "01HWQ76NTNTS8Q6JZZHEXV8PYH",
       "columnId": "01HWQ76NTNTS8Q6JZZHEXV8PYH_0_city_text",
       "pullFromId": "82c527d7-e09b-46be-be4a-b51f6af43e0e"
   }
 ]
}
]

In the example above, the column "Location-city" contains a reference object, indicating that it's pulled from another column. Here's what each attribute means:

entityType: Specifies the type of entity from which the column is pulled. In this case, it's a collection.
entityId: Represents the unique identifier of the entity (collection) from which the column is pulled.
columnId: Indicates the ID of the column in the referenced entity (collection). This is the column from which data is pulled.
pullFromId: Denotes the specific ID of the data pulled from the referenced entity (collection).

Create Collection Record:

Prepare the payload with the record data. Specify the new field values you want to apply to the record.

Example Request:

const payload = {
  tenant: {
    accountId: '{{accountId}}',
    moduleId: '{{moduleId}}',
  },
  collectionId: '{{collectionId}}',
  records: [
    {
      01HWQ7CW7T626WY2A3KV603ZNF_0_name_text: 'John Doe',
    },
  ],
}

Update Collection Record:

Prepare the payload with the updated record data. Specify the new field values you want to apply to the existing record. When updating a record, ensure to include the recordId along with the updated record data.

Example Request:

const payload = {
  tenant: {
    accountId: '{{accountId}}',
    moduleId: '{{moduleId}}',
  },
  collectionId: '{{collectionId}}',
  records: [
    {
      01HWQ7CW7T626WY2A3KV603ZNF_0_name_text: 'John Doe',
      recordId: '{{recordId}}', // Include recordId when updating
    },
  ],
}

Create or Update Collection Record with References:

When creating or updating a collection record with references, include the reference data along with the record data.

Example Request:

const payloadWithReferences = {
  tenant: {
    accountId: '{{accountId}}',
    moduleId: '{{moduleId}}',
  },
  collectionId: '{{collectionId}}',
  records: [
    {
      01HWQ7CW7T626WY2A3KV603ZNF_0_name_text: 'John Doe',
      references: {
        '01HWQ7CW7T626WY2A3KV603ZNF_0_lcity_text': '{{cityRecordId}}', // Reference to a city record
      },
    },
  ],
}

Data Types for Collection Records

When creating records within your collection, you'll need to provide data in specific formats depending on the data type of each column. Here's a breakdown of some common data types and how to represent them in your payload:

Text:
This applies to any textual information you want to store, like names, descriptions, or short notes. Use quotation marks (") to enclose the text. (Example: "New Customer Name")

Number:
Use numeric values for quantities, amounts, or any numerical data. (Example: 25, 3.14)

Currency:
If you're storing monetary values, use a numeric value representing the amount. (Example: 100)

GPS Coordinates:
For geographical locations, represent them using a comma-separated string with latitude and longitude values. (Example: "-77.0364,38.8951")

Single Select List:
When a column offers predefined options to choose from, use the string value corresponding to your selection. (Example: "Bronze" for a membership tier)

Long Text:
This is for storing extensive textual content, like product descriptions or detailed reports. (Example: "This is a lengthy text describing the product features...")

Address:
Provide a complete address string, including street address, city, state, and zip code (if applicable). (Example: "123 Main Street, Anytown, CA 12345")

Date and Time:
Use the YYYY-MM-DD format (e.g., "2024-05-24") to represent dates. You might need to adjust the format based on choosen Date format.

Email Address:
If your collection supports email addresses, enter a valid email address following the standard format (e.g., [email protected]).

IP Address:
This could be an IPv4 address (e.g., "123.123.123.123") or an IPv6 address (e.g., "2001:0db8:85a3:0000:0000:8a2e:0370:7334") depending on the data type supported by the column.

Multi-Select List:
Data Format: When your collection API supports multi-select options, you'll need to provide comma-separated values within a string to represent the options you've chosen from the list.
Example: If a "Categories" column allows multiple selections, you could include "Category A, Category B" in your payload to indicate those selections.

Example JSON Payload

Here's an example JSON payload that demonstrates how you might create a new record with various data types within your collection:

{
  "tenant": {
    "accountId": "{{accountId}}",
    "moduleId": "{{moduleId}}"
  },
  "collectionId": "{{collectionId}}",
  "records": [
    {
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_currency_currency": 25,
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_gpscoordinates_gpscoordinates": "-77.0364,38.8951",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_singleselectlist_singleselectlist": "Option 2",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_multipleselect_multipleselectlist": "Category A, Category B",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_name_text": "John Doe",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_longtext_longtext": "Lorem Ipsum is simply dummy text of the printing and typesetting industry",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_address_address": "address line 4",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_dateandtime_datetime": "2024-05-23",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_email_emailaddress": "[email protected]",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_ipaddress_ipaddress": "123.123.123.123",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_ipaddressv6_ipaddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_numeric_numeric": 32,
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_percent_percent": 50,
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_phonenumber_phone": "12345677890",
      "01HXGNRYZ0P3HAH4F70QA30GAG_0_url_url": "https://www.google.com/"
    }
  ]
}