Campos personalizados

Endpoints para gerenciar a informação de Campos na sua conta do RD Station.

Métodos disponíveis

Returns a list of Fields and their attributes from the current account. A field can be either default or custom, as follow:
  • Default fields are standard fields that represent RD Station's Contact's basic information.
  • Custom fields are fields that represent unique Contact's information accordingly to your organization and that were created by RD Station's users.
Response Body
Field Type Description
uuid String The unique uuid associated to each RD Station field.
api_identifier String The API identifier of the field.
custom_field Boolean It sets to false for default fields and true for custom fields.
data_type String The type of the field's data. The possible values are BOOLEAN, STRING, STRING[] and INTEGER.
name Localized Strings Name of the Field in RD Station.

This attribute is a Localized String object where its value(s) are included in inner (String) language attributes (only "pt-BR" is supported for now). Example: 
{
  "name": {
    "pt-BR": "Meu campo"
  }
}
label Localized Strings Label of the field in RD Station's forms.

This attribute is a Localized String object where its value(s) are included in inner (String) language attributes (only "pt-BR" is supported for now). Example: 
{
  "label": {
    "pt-BR": "Selecione a opção"
  }
}
presentation_type String The type of the field. The possible values are TEXT_INPUT, TEXT_AREA, URL_INPUT, PHONE_INPUT, EMAIL_INPUT, CHECK_BOX, NUMBER_INPUT, COMBO_BOX, RADIO_BUTTON and MULTIPLE_CHOICE.
validation_rules Object The validation rules of the field.
valid_options Array List of valid options for fields that support multiple options.

This attribute contains inner objects that have a "value" and a "label" (which is a Localized String) attribute. Example: 
{
  "valid_options": [
    {
      "value": "option_1",
      "label": {
        "pt-BR": "option_1"
      }
    }
  ]
}

Inner object attributes:
  • value attribute represents the meaning of the object in data level
  • label attribute is a Localized String that exists for presentation layers purpose.
Example:

Code: 200

{
  "fields": [
    {
      "uuid": "fdeba6ec-f1cf-4b13-b2ea-e93d47c0d828",
      "api_identifier": "name",
      "custom_field": false,
      "data_type": "STRING",
      "name": {
        "default": "nome",
        "pt-BR": "nome"
      },
      "label": {
        "default": "Nome completo",
        "pt-BR": "Nome completo"
      },
      "presentation_type": "TEXT_INPUT",
      "validation_rules": {}
    },
    {
      "uuid": "f0a3dd8a-f044-432c-a1ce-1bb559d6edf4",
      "api_identifier": "cf_language",
      "custom_field":  true,
      "data_type": "STRING[]",
      "name": {
        "default": "Idioma",
        "pt-BR": "Idioma"
      },
      "label": {
        "default": "Selecione o idioma",
        "pt-BR": "Selecione o idioma"
      },
      "presentation_type": "CHECK_BOX",
      "validation_rules": {
        "valid_options": [
          {
            "value": "Português",
            "label": {
              "default": "Português",
              "pt-BR": "Português"
            }
          },
          {
            "value": "Inglês",
            "label": {
              "default": "Inglês",
              "pt-BR": "Inglês"
            }
          },
          {
            "value": "Espanhol",
            "label": {
              "default": "Espanhol",
              "pt-BR": "Espanhol"
            }
          }
        ]
      }
    }
  ]
}
Creates a Field for the current account.
Request body parameters
Field Type Required Description
api_identifier String true Unique identifier to reference this field for the Contact's endpoints calls. A field's api_identifier cannot be changed afterwards.
data_type String true Data type to which the field's value should be formatted to
label Localized Strings true Label of the field in RD Station's forms.

This parameter is a Localized String object where its value(s) are included in inner (String) language attributes (only "pt-BR" is supported for now). Example: 
{
  "label": {
    "pt-BR": "Selecione a opção"
  }
}
name Localized Strings true Name of the Field in RD Station.

This parameter is a Localized String object where its value(s) are included in inner (String) language attributes (only "pt-BR" is supported for now). Example: 
{
  "name": {
    "pt-BR": "Meu campo"
  }
}
presentation_type String true Type of the Field in RD Station forms
validation_rules Object true Rules to validate the Field's value.
valid_options Array false List of valid options for fields that support multiple options.

This parameter contains inner objects that has a "value" and a "label" (which is a Localized String) attribute. Example: 
{
  "valid_options": [
    {
      "value": "option_1",
      "label": {
        "pt-BR": "option_1"
      }
    }
  ]
}

Inner object attributes:
  • value attribute is the identifier of the item. Will be used to relate options in across languages.
  • label attribute is a Localized String that exists for presentation layers purpose.
Validations
Payload validations:
Error type Rule
BAD_REQUEST Localized Strings objects can only send "pt-BR" values.
Attributes validations:
Field Error type Rule
api_identifier INVALID It must start with the prefix cf_, it must have alphanumerics and underscores. It can't have special characters.
api_identifier TAKEN It must be unique within the current account.
api_identifier TOO_LONG It is limited to 64 characters.
data_type INVALID It must match the presentation_type, you can see the matches between data_type and presentation_type on the table below.
label TOO_LONG It is limited to 1000 characters.
name TAKEN It must be unique within the current account.
name EXCLUSION It can't use reserved strings.
presentation_type INCLUSION It must be one of these types: TEXT_INPUT, TEXT_AREA, URL_INPUT, PHONE_INPUT, EMAIL_INPUT, CHECK_BOX, NUMBER_INPUT, COMBO_BOX, RADIO_BUTTON and MULTIPLE_CHOICE.
presentation_type EXCLUSION It cannot change to an incompatible presentation type when it is being used.
valid_options TOO_SHORT It must have at least one item. Only applicable when presentation type is MULTIPLE_CHOICE, COMBO_BOX or RADIO_BUTTON.
valid_options INVALID It can't have repeated items.
valid_options / value TOO_SHORT Valid options value must be filled.
Valid data types:
presentation_type data_type
TEXT_INPUT STRING
EMAIL_INPUT STRING
COMBO_BOX STRING
URL_INPUT STRING
TEXT_AREA STRING
RADIO_BUTTON STRING
PHONE_INPUT STRING
NUMBER_INPUT INTEGER
CHECK_BOX BOOLEAN
MULTIPLE_CHOICE STRING[]
Valid presentation type changes (when field is being used):
From To
CHECK_BOX (cannot change)
TEXT_INPUT TEXT_AREA
TEXT_AREA TEXT_INPUT
EMAIL_INPUT TEXT_AREA, TEXT_INPUT
URL_INPUT TEXT_AREA, TEXT_INPUT
NUMBER_INPUT TEXT_AREA, TEXT_INPUT
PHONE_INPUT TEXT_AREA, TEXT_INPUT
MULTIPLE_CHOICE TEXT_AREA, TEXT_INPUT
COMBO_BOX TEXT_AREA, TEXT_INPUT, RADIO_BUTTON
RADIO_BUTTON TEXT_AREA, TEXT_INPUT, COMBO_BOX
Reserved Strings

account_id, address, already_received_email, available_for_mailing, behavior_score, bio, block_events_count, cargo, celular, cidade, city, city_id, company, company_id, company_sector_id, conversions_sum, country, created_at, email, empresa, estado, facebook, id, job_title, last_conversion_date, last_email_interaction_timestamp, last_visit_date, lead_id, leads_manager_id, lifecycle_stage, linkedin, mobile_phone, name, nome, opportunity, opt-in email, personal_phone, pg_tags, phone, private_token, site, size, state, state_id, telefone, token_rdstation, twitter, uf, updated_at, user_id, uuid, website

Request body example
{
  "name": {
    "pt-BR": "Meu campo customizado"
  },
  "label": {
    "pt-BR": "Selecione uma das opções"
  },
  "api_identifier": "cf_my_custom_field",
  "data_type": "STRING",
  "presentation_type": "COMBO_BOX",
  "validation_rules": {
    "valid_options": [
      {
        "value": "opcao_1",
        "label": {
          "pt-BR": "opcao_1"
        }
      },
      {
        "value": "opcao_2",
        "label": {
          "pt-BR": "opcao_2"
        }
      }
    ]
  }
}
Response Body
Field Type Description
uuid String The unique uuid associated to each RD Station field.
Response examples:

Success | Code: 201

{
  "uuid": "fdeba6ec-f1cf-4b13-b2ea-e93d47c0d828"
}

Error | Code: 400

Request errors
{
  "errors": {
    "error_type": "BAD_REQUEST",
    "error_message": "payload should provide pt-BR values only"
  }
}
Attributes errors
{
  "errors":{
    "name": {
      "pt-BR": [
        {
          "error_type": "CANNOT_BE_BLANK",
          "error_message": "can not be blank"
        },
        {
          "error_type": "TAKEN",
          "error_message": "is already in use"
        },
        {
          "error_type": "EXCLUSION",
          "error_message": "is already in use"
        }
      ]
    },
    "label": {
      "pt-BR": [
        {
          "error_type": "CANNOT_BE_BLANK",
          "error_message": "can not be blank"
        },
        {
          "error_type": "TOO_LONG",
          "error_message": "is too long (maximum 1000 characters)"
        }
      ]
    },
    "api_identifier":[
      {
        "error_type": "INVALID",
        "error_message": "must have the prefix 'cf_' and it can only have lowercase alphanumerics and underscores"
      },
      {
        "error_type": "TOO_LONG",
        "error_message": "is too long (maximum 64 characters)"
      },
      {
        "error_type": "TAKEN",
        "error_message": "is already in use"
      }
    ],
    "data_type": [
      {
        "error_type": "INVALID",
        "error_message": "only supports [data_type] as data type"
      }
    ],
    "validation_rules": {
      "valid_options": [
        {
          "error_type": "TOO_SHORT",
          "error_message": "must be fulfilled for the chosen field type"
        },
        {
          "error_type": "INVALID",
          "error_message": "has repeated items"
        }
      ]
    }
  }
}
Updates a Field for the current account. It supports partial updates.
Request body parameters
Field Type Required Description
data_type String true Data type to which the field's value should be formatted to
label Localized Strings true Label of the field in RD Station's forms.

This parameter is a Localized String object where its value(s) are included in inner (String) language attributes (only "pt-BR" is supported for now). Example: 
{
  "label": {
    "pt-BR": "Selecione a opção"
  }
}
name Localized Strings true Name of the Field in RD Station.

This parameter is a Localized String object where its value(s) are included in inner (String) language attributes (only "pt-BR" is supported for now). Example: 
{
  "name": {
    "pt-BR": "Meu campo"
  }
}
presentation_type String true Type of the Field in RD Station forms
validation_rules Object true Rules to validate the Field's value.
valid_options Array false List of valid options for fields that support multiple options.

This parameter contains inner objects that has a "value" and a "label" (which is a Localized String) attribute. Example: 
{
  "valid_options": [
    {
      "value": "option_1",
      "label": {
        "pt-BR": "option_1"
      }
    }
  ]
}

Inner object attributes:
  • value attribute is the identifier of the item. Will be used to relate options in across languages.
  • label attribute is a Localized String that exists for presentation layers purpose.
Validations
Payload validations:
Error type Rule
BAD_REQUEST Localized Strings objects can only send "pt-BR" values.
Attributes validations:
Field Error type Rule
data_type INVALID It must match the presentation_type, you can see the matches between data_type and presentation_type on the table below.
label TOO_LONG It is limited to 1000 characters.
name TAKEN It must be unique within the current account.
name EXCLUSION It can't use reserved strings.
presentation_type INCLUSION It must be one of these types: TEXT_INPUT, TEXT_AREA, URL_INPUT, PHONE_INPUT, EMAIL_INPUT, CHECK_BOX, NUMBER_INPUT, COMBO_BOX, RADIO_BUTTON and MULTIPLE_CHOICE.
presentation_type EXCLUSION It cannot change to an incompatible presentation type when it is being used.
valid_options TOO_SHORT It must have at least one item. Only applicable when presentation type is MULTIPLE_CHOICE, COMBO_BOX or RADIO_BUTTON.
valid_options INVALID It can't have repeated items.
valid_options / value TOO_SHORT Valid options value must be filled.
Valid data types:
presentation_type data_type
TEXT_INPUT STRING
EMAIL_INPUT STRING
COMBO_BOX STRING
URL_INPUT STRING
TEXT_AREA STRING
RADIO_BUTTON STRING
PHONE_INPUT STRING
NUMBER_INPUT INTEGER
CHECK_BOX BOOLEAN
MULTIPLE_CHOICE STRING[]
Valid presentation type changes (when field is being used):
From To
CHECK_BOX (cannot change)
TEXT_INPUT TEXT_AREA
TEXT_AREA TEXT_INPUT
EMAIL_INPUT TEXT_AREA, TEXT_INPUT
URL_INPUT TEXT_AREA, TEXT_INPUT
NUMBER_INPUT TEXT_AREA, TEXT_INPUT
PHONE_INPUT TEXT_AREA, TEXT_INPUT
MULTIPLE_CHOICE TEXT_AREA, TEXT_INPUT
COMBO_BOX TEXT_AREA, TEXT_INPUT, RADIO_BUTTON
RADIO_BUTTON TEXT_AREA, TEXT_INPUT, COMBO_BOX
Reserved Strings

account_id, address, already_received_email, available_for_mailing, behavior_score, bio, block_events_count, cargo, celular, cidade, city, city_id, company, company_id, company_sector_id, conversions_sum, country, created_at, email, empresa, estado, facebook, id, job_title, last_conversion_date, last_email_interaction_timestamp, last_visit_date, lead_id, leads_manager_id, lifecycle_stage, linkedin, mobile_phone, name, nome, opportunity, opt-in email, personal_phone, pg_tags, phone, private_token, site, size, state, state_id, telefone, token_rdstation, twitter, uf, updated_at, user_id, uuid, website

Request body example

Update all attributes:

{
  "name": {
    "pt-BR": "Meu campo customizado"
  },
  "label": {
    "pt-BR": "Selecione uma das opções"
  },
  "data_type": "STRING",
  "presentation_type": "COMBO_BOX",
  "validation_rules": {
    "valid_options": [
      {
        "value": "opcao_1",
        "label": {
          "pt-BR": "opcao_1"
        }
      },
      {
        "value": "opcao_2",
        "label": {
          "pt-BR": "opcao_2"
        }
      }
    ]
  }
}

Update a single attribute:

{
  "name": { "pt-BR": "Meu campo customizado atualizado" }
}
Response examples:

Success | Code: 200

(No response body)

Error | Code: 400

Request errors
{
  "errors": {
    "error_type": "BAD_REQUEST",
    "error_message": "payload should provide pt-BR values only"
  }
}
Attributes errors
{
  "errors":{
    "name": {
      "pt-BR": [
        {
          "error_type": "CANNOT_BE_BLANK",
          "error_message": "can not be blank"
        },
        {
          "error_type": "TAKEN",
          "error_message": "is already in use"
        },
        {
          "error_type": "EXCLUSION",
          "error_message": "is already in use"
        }
      ]
    },
    "label": {
      "pt-BR": [
        {
          "error_type": "CANNOT_BE_BLANK",
          "error_message": "can not be blank"
        },
        {
          "error_type": "TOO_LONG",
          "error_message": "is too long (maximum 1000 characters)"
        }
      ]
    },
    "data_type": [
      {
        "error_type": "INVALID",
        "error_message": "only supports [data_type] as data type"
      }
    ],
    "validation_rules": {
      "valid_options": [
        {
          "error_type": "TOO_SHORT",
          "error_message": "must be fulfilled for the chosen field type"
        },
        {
          "error_type": "INVALID",
          "error_message": "has repeated items"
        }
      ]
    }
  }
}
Deletes a Field from the current account.
Request parameters
Field Type Required Description
uuid String true The unique uuid associated to each RD Station field.
Response examples:

Success | Code: 204

Error | Code: 400

{
  "errors":{
    "base":[
      {
        "error_type": "INVALID",
        "error_message": "a default field can not be changed"
      },
      {
        "error_type": "INVALID",
        "error_message": "this custom field is used in one of its segmentation lists"
      },
      {
        "error_type": "INVALID",
        "error_message": "this custom field is used in social conversion"
      }
    ],
  }
}

Error | Code: 404

{
  "errors":{
     {
       "error_type": "RESOURCE_NOT_FOUND",
       "error_message": "the resource couldn't be found"
     }
  }
}

More info

Localized Strings
Localized strings are values that can exists in multiple languagens. They exist so our API clients can make use of the same data in different language contexts.

The only language supported right now is pt-BR, but we intend to extend this support in the future.

This kind of values has the following structure: 
{
  "field": {
    "pt-BR": "Madeira",
    "en-US": "Wood"
  }
}
The locale string is case sensitive; therefore pt-br won't be accepted.