Versions Compared

Version Old Version 2 New Version 3
Changes made by

Thibault Galharret

Thibault Galharret

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
stylenone

Default form

...

tel

country

Add custom fields

Classic fields

Field

Type

Mandatory

Description

name

string

Yes

This key is used to give the identifier of the field.

This id must match with parameters used in POST /customers request or PATCH /customers/<id>

Expand
titleAllowed values

  • Contact fields: title, first_name, last_name, phone_number, email, company_name, mobile_number

  • Address fields: address_1, address_2, address_3, city, zip_code, country

  • Custom fields: information.{custom_field}, external_id

target

string

No

Indicates whether the field should be saved in the customer structure or the address structure. By default, customer is applied.

Only used for information.{custom_field} and external_id names, the others are automatically redirected to the right structure.

Expand
titleAllowed values

  • customer

  • address

type

string

No

Type of the field. By default, the text type is used.

Expand
titleAllowed values

  • text - returns a string

  • email - returns a string

  • tel- returns a string

  • password - returns a string

  • flip-switch - returns a boolean

  • list - returns a string or an array of string depending on the ‘multiple’ value

required

boolean

No

Indicates whether the field is mandatory or not. By default, fields are optional.

position_after

string

No

This key defines the name of the form element to which it must be placed after. Please note, the form element must be in the default form or declared before in the same form.

It it also possible to place the element on the top of the form with the value :first. If multiple elements are placed in first position, they will be placed in the order in which they are configured.

If not defined, the element form will be placed at the bottom of the form.

Expand
titleExamples

  • If I want my field to appear after the country field of the default form : "position_after": "country"

  • If I want my field to appear at the top of the form : "position_after": ":first"

  • If I want my field to appear at the bottom of the form, I leave it blank.

validation

object[string]

No

Enables to add custom validation to the field, which will be checked when the create button is clicked.

Expand
titleAllowed values

These 3 types of validation can be configured alone or together.

  • min_characters (int) - minimum number of characters required

  • max_characters (int) - maximum number of characters required

  • regex (string) - Custom regular expression used to verify the field. More information Here.

Expand
titleExampleExamples

  • Require a 5-digit postcode

Code Block
languagejson
"validation": {
  "min_characters": 5,
  "max_characters": 5
}

  • Use a custom validation for UK postcode

Code Block
languagejson
"validation": {
  "regex": "^([a-zA-Z]){1}([0-9][0-9]|[0-9]|[a-zA-Z][0-9][a-zA-Z]|[a-zAZ][0-9][0-9]|[a-zAZ][0-9]|[0-9][a-zAZ]){1}([ ])*([0-9][a-zA-z][a-zA-z]){1}$"
}
Note

Regexes with ‘\’ must escape by doubling it "\\"

Fields if the field is a list

Field

Type

Mandatory

Description

options

array[string]

No

List of values displayed in the drop down.

Options inside will be translated with the key crm.information._{name}_options.{option}

Expand
titleExample

List of options for the title custom field

Code Block
"options": [
    "MR",
    "MRS"
],

multiple

bool

No

Indicates if multiple selection can be done.

searchable

bool

No

Indicates if drop down elements are searchable.

initial_value

multiple

searchablestring

No

Indicates the pre-selected option.

Change classic fields

Request entries

  • Regarding the address:

    • address_1 - sent in the customer.addresses.[0].lines.[0] field of the POST /customers query

    • address_2 - sent in the customer.addresses.[0].lines.[1] field of the POST /customers query

    • city - sent in the customer.addresses.[0].city field of the POST /customers query

    • zip_code - sent in the customer.addresses.[0].zip_code field of the POST /customers query

    • country - sent in the customer.addresses.[0].regions.country.code field of the POST /customers query

  • Regarding the contact - sent in the customer.addresses.[0].contact AND customer.contact fields of the POST /customers query

    • title

    • first_name

    • last_name

    • phone_number

    • email

    • company_name

    • mobile_number

  • Regarding custom information

    • information.{custom_field} sent in the customer.addresses.[0].information field if target = address / sent in the customer.contact field if target = address

    • external_id sent in the customer.external_id field. The target need to be set as customer.

Please note, the label of the field will be translated based on the translation key crm.<name>.

...

Key

...

Mandatory

...

Type 

...

Allowed values

...

Default value

...

Description

...

target

...

No

...

string

...

customer

address

...

customer

...

This key defines which form is targetted: customer or address. By default if target is not given, customer is applied.

Only useful for information.{custom_field} and external_id fields

...

type

...

No

...

string

...

text, email, tel, password, flip-switch,  list

...

text

...

This key defines the HTML element is used.

  • text is for HTML input type text. Value returned will be a string

  • email is for HTML input type email. Value returned will be a string

  • tel is for HTML input type tel. Value returned will be a string

  • password is for HTML input type password. Value returned will be a string

  • flip-switch is for toggle switch (yes/no). Value returned will be boolean true for YES, and false for NO

  • list is for drop-down. If key multiple:false, then value returned will be a string. If key multiple:true, then value returned will be an array of string

...

options

...

No

...

string[]

...

/

...

/

...

This key is usable only if key:list
It defines values inside dropdown.

Content inside will be translated based on translation keys crm.information._<list_name>_options.<option_value> where <list_name> is the name of the list that will use options, and <option_value> is the value of the option.

...

initial_value

...

No

...

string / bool

...

/

...

/

...

This key is usable ONLY if key:list
It defines which value will be preselected.

If multiple:true, use comma ',' to separate values.

...

multiple

...

No

...

bool

...

/

...

false

...

This key is usable ONLY if key type:list.
It defines if multiple selection can be done.

If key multiple:false, then value returned will be a string. If key multiple:true, then value returned will be an array of string. 

...

searchable

...

No

...

bool

...

/

...

false

...

This key is usable only if key type:list
It defines if dropdown elements are searchable.

...

required

...

No

...

bool

...

/

...

false

...

This key force completion to validate form.
true to force.

...

position_after

...

No

...

string

...

/

...

/

This key defines the name of the form element to which it must be placed after. 
":first" is a keyword to place the element on the top of the form.
If multiple elements are with position_after::first, they will be placed on the top of the form in the order of their declaration (first declared will be on the top).

Element which is named in this key MUST have been declared before in the same form as this one.

...

...

External CRM

External CRM may raised error (exemple email adress/phone number already used).
If so, project interface MUST return a 409 error including:

  • field that is the field related to the conflit. Value MUST be email or phone_number

  • message which is the error message to display in the interface

The error message will be display on the form.