About the Extended Fields API
The Extended Fields API provides functionality for creating and managing extended field definitions. Extended fields enable you to retrieve and store specific information relevant to your site. Basic fields, such as name, email, and phone, are stored in the contact's default properties. Additional custom contact properties are stored in extended fields.
With the Extended Fields API, you can:
- Create a new extended field.
- Delete an extended field.
- Update an extended field by renaming its display name.
- Query extended fields.
Before you begin
It is important to note the following points before you begin to code:
- When you create a new extended field, it becomes available to use for all contacts. The field is blank by default.
- Possible data types of extended fields include:
- text
- number
- date
- url
- Extended fields are represented as key-value pairs in the contact's object in
info.extendedfields
. To manage the extended fields of an individual contact, use the Contacts API.
Terminology
- Extended field: A customized field that can store additional information for a contact. A contact’s extended field data is available in the
contact
object underinfo.extendedFields
. There are 2 types of extended fields:- System field: An extended field added by Wix apps. System fields often enrich contacts with data from Wix apps, such as Wix Stores or Wix Members. System fields cannot be renamed and are typically read-only.
- Custom field: An extended field added by site admins or 3rd-party apps. Custom fields can be renamed, and their data can be written by any site admin or 3rd-party app.
Setup
To use the ExtendedFields API, install the @wix/crm
package using npm or Yarn:
1npm install @wix/crm
or
1yarn add @wix/crm
Then import { extendedFields }
from @wix/crm
:
1import { extendedFields } from '@wix/crm'
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes an extended field.
The deleteExtendedField()
function returns a Promise that resolves when the specified extended field is deleted.
When an extended field is deleted, any contact data stored in the field is permanently deleted as well.
Permission Scopes
For app development, you must have one of the following permission scopes:function deleteExtendedField(key: string): Promise<void>
Extended field key.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a custom field with a given name, or creates one if it doesn't exist.
The findOrCreateExtendedField()
function returns a Promise that resolves when the specified custom field is found or created.
Successful calls to findOrCreateExtendedField()
always return an extended field, which can be passed to subsequent function calls.
To find an existing extended field without potentially creating a new one, use getExtendedField()
or queryExtendedFields()
.
Permission Scopes
For app development, you must have one of the following permission scopes:function findOrCreateExtendedField(displayName: string, dataType: FieldDataType): Promise<FindOrCreateExtendedFieldResponse>
Display name to find or create.
If an existing custom field is an exact match for the specified displayName, the existing field is returned. If not, a new field is created and returned.
Type of data the field holds. Ignored if an existing field is an exact match for the specified display name. One of:
- "TEXT": Accepts strings.
- "NUMBER": Accepts floats.
- "DATE": Accepts dates formatted as YYYY-MM-DD.
- "URL": Accepts strings. Prepends https:// if no protocol is included.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves an extended field.
The getExtendedField()
function returns a Promise that resolves when the extended field is retrieved.
Permission Scopes
For app development, you must have one of the following permission scopes:function getExtendedField(key: string): Promise<ExtendedField>
Extended field key.
When accessing contact data, extended field values are available at fields[key]. For example, if the key is "custom.notes", the value can be accessed at fields["custom.notes"].
Once set, key cannot be modified, even if displayName changes.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a query to retrieve a list of extended fields.
The queryExtendedFields()
function builds a query to retrieve a list of extended fields and returns an FieldsQueryBuilder
object.
The returned object contains the query definition, which is used to run the query using the find()
function.
You can refine the query by chaining FieldsQueryBuilder
functions onto the query. FieldsQueryBuilder
functions enable you to filter, sort, and control the results that queryExtendedFields()
returns.
queryExtendedFields()
runs with these FieldsQueryBuilder
defaults, which you can override:
skip()
limit(50)
descending('_createdDate')
The following FieldsQueryBuilder
functions are supported for queryExtendedFields()
. For a full description of the Extended Field
object, see the object returned for the items
property in FieldsQueryResult
.
PROPERTY | SUPPORTED FILTERS & SORTING |
---|---|
namespace | eq() ,ne() |
key | eq() ,ne() ,in() |
displayName | eq() ,ne() ,in() ,startsWith() ,ascending() ,descending() |
dataType | eq() ,ne() |
fieldType | eq() |
_createdDate | eq() ,ne() ,gt() ,lt() ,ge() ,le() ,ascending() ,descending() |
_updatedDate | eq() ,ne() ,gt() ,lt() ,ge() ,le() ,ascending() ,descending() |
Permission Scopes
For app development, you must have one of the following permission scopes:function queryExtendedFields(): FieldsQueryBuilder
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Renames an extended field.
The renameExtendedField()
function returns a Promise that resolves when the specified extended field's display name is changed
Permission Scopes
For app development, you must have one of the following permission scopes:function renameExtendedField(key: string, field: RenameExtendedField): Promise<ExtendedField>
Extended field key.
When accessing contact data, extended field values are available at fields[key]. For example, if the key is "custom.notes", the value can be accessed at fields["custom.notes"].
Once set, key cannot be modified, even if displayName changes.
Extended field to rename.