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 under info.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.

Was this helpful?

Yes

Setup

To use the ExtendedFields API, install the @wix/crm package using npm or Yarn:

Copy

1npm install @wix/crm

Copy

1yarn add @wix/crm

Then import { extendedFields } from @wix/crm:

Copy

1import { extendedFields } from '@wix/crm'

Was this helpful?

Yes

deleteExtendedField( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function deleteExtendedField(key: string): Promise<void>

Method Parameters

keystringRequired

Extended field key.

Was this helpful?

Yes

findOrCreateExtendedField( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function findOrCreateExtendedField(displayName: string, dataType: FieldDataType): Promise<FindOrCreateExtendedFieldResponse>

Method Parameters

displayNamestringRequired

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.

dataTypeFieldDataTypeRequired

5 enum supported values:

DATENUMBERTEXTUNKNOWN_DATA_TYPEURL

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.

Returns

Return Type:Promise<FindOrCreateExtendedFieldResponse>

Was this helpful?

Yes

getExtendedField( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function getExtendedField(key: string): Promise<ExtendedField>

Method Parameters

keystringRequired

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.

Returns

Return Type:Promise<ExtendedField>

Was this helpful?

Yes

queryExtendedFields( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function queryExtendedFields(): FieldsQueryBuilder

Request

This method does not take any parameters

Returns

Return Type:FieldsQueryBuilder

Was this helpful?

Yes

renameExtendedField( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function renameExtendedField(key: string, field: RenameExtendedField): Promise<ExtendedField>

Method Parameters

keystringRequired

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.

fieldRenameExtendedFieldRequired

Extended field to rename.

Returns

Return Type:Promise<ExtendedField>

Was this helpful?

Yes