Fields ###### Use this endpoint to work with Salesbox's Contact/Company fields. **Using Salesbox's API** You can interact with this API through the various HTTP endpoints as described in this document. Base Endpoint ************ .. code-block:: text https://segmentai.salesbox.com.br/api/fields Get field ********* Get an individual field by ID. **HTTP Request** ``GET /fields/contact/ID`` or ``GET /fields/company/ID`` **Response** ``Expected Response Code: 200`` .. code-block:: json { "field":{ "isPublished":true, "dateAdded":"2024-01-10T13:02:52+00:00", "createdBy":1, "createdByUser":"John Doe", "dateModified":null, "modifiedBy":null, "modifiedByUser":null, "id":165, "label":"Test field", "alias":"test_field", "type":"text", "group":null, "order":36, "object":"contact", "defaultValue":null, "isRequired":false, "isPubliclyUpdatable":false, "isUniqueIdentifier":0, "properties":[] } } **Field Properties** .. list-table:: :header-rows: 1 * - Name - Type - Description * - ``id`` - int - ID of the field * - ``isPublished`` - boolean - Availability for use * - ``publishUp`` - datetime/null - Field available from date/time * - ``publishDown`` - datetime/null - Field unavailable from date/time * - ``dateAdded`` - ``datetime`` - Field creation date/time * - ``createdBy`` - int - ID of the User that created the field * - ``createdByUser`` - string - Name of the User that created the field * - ``dateModified`` - datetime/null - Field modified date/time * - ``modifiedBy`` - int - ID of the User that last modified the field * - ``modifiedByUser`` - string - Name of the User that last modified the field * - ``label`` - string - Name of the field * - ``alias`` - string - Unique alias of the field used in the Form Field name attributes * - ``description`` - string/null - Description of the field * - ``type`` - string - Field type * - ``group`` - string - Group of the fields where the field belongs * - ``order`` - int - Order number of the field * - ``object`` - string - Which object uses the field, Contact or Company * - ``defaultValue`` - string - Default value of the field * - ``isRequired`` - boolean - ``true`` if this is a required field * - ``isPubliclyUpdatable`` - boolean - ``true`` if public requests can change the field value * - ``isUniqueIdentifier`` - boolean - ``true`` if the field is a unique identifier * - ``properties`` - array - Field options if the field type needs some. List Fields ********** Get a list of all fields. **HTTP Request** ``GET /fields/contact`` or ``GET /fields/company`` **Response** ``Expected Response Code: 200`` .. code-block:: json { "total":71, "fields":[ { "isPublished":true, "dateAdded":"2024-01-12T11:31:13+00:00", "createdBy":1, "createdByUser":"John Doe", "dateModified":"2024-01-12T11:31:30+00:00", "modifiedBy":1, "modifiedByUser":"John Doe", "id":100, "label":"Multiselect test", "alias":"multiselect_test", "type":"multiselect", "group":"core", "order":3, "object":"contact", "defaultValue":null, "isRequired":false, "isPubliclyUpdatable":false, "isUniqueIdentifier":false, "properties":{ "list":[ { "label":"Option 1", "value":"opt1" }, { "label":"Option 2", "value":"opt2" } ] } } ] } Create field ************ .. code-block:: php 'API test field', 'type' => 'text', ); $field = $fieldApi->create($data); **Multiselect field** .. code-block:: php 'API test field', 'type' => 'multiselect', 'isPubliclyUpdatable' => true, 'properties' => array( 'list' => array( array( 'label' => 'label 1', 'value' => 'value 1' ), array( 'label' => 'label 2', 'value' => 'value 2' ) ) ) ); $field = $fieldApi->create($data); Create a new field. **HTTP Request** ``POST /fields/contact/new`` or ``POST /fields/company/new`` **POST parameters** .. list-table:: :header-rows: 1 * - Name - Type - Description * - ``label`` - string - Name of the field * - ``alias`` - string - Unique alias of the field used in the Form Field name attributes * - ``description`` - string/null - Description of the field * - ``type`` - string - Field type * - ``group`` - string - Group of the fields where the field belongs * - ``order`` - int - Order number of the field * - ``object`` - string - Which object uses the field, Contact or Company * - ``defaultValue`` - string - Default value of the field * - ``isRequired`` - boolean - ``true`` if this is a required field * - ``isPubliclyUpdatable`` - boolean - ``true`` if public requests can change the field value * - ``isUniqueIdentifier`` - boolean - ``true`` if the field is unique identifier * - ``properties`` - array - Field options if the field type needs some **Response** ``Expected Response Code: 201`` **Properties** Same as `Get Field <#get-field>`_. Edit field ********** .. code-block:: php 'API test field', 'type' => 'text', ); // Create new a field if ID 1 isn't found? $createIfNotFound = true; $field = $fieldApi->edit($id, $data, $createIfNotFound); Edit a new field. Field that this supports PUT or PATCH depending on the desired behavior. **PUT** creates a field if the given ID doesn't exist. **PATCH** fails if the field with the given ID doesn't exist and updates the field values with the values field the request. **HTTP Request** To edit a field and return a 404 if the field isn't found: ``PATCH /fields/contact/ID/edit`` or ``PATCH /fields/company/ID/edit`` To edit a field and create a new one if the field isn't found: ``PUT /fields/contact/ID/edit`` or ``PUT /fields/company/ID/edit`` **POST Parameters** .. list-table:: :header-rows: 1 * - Name - Type - Description * - ``label`` - string - Name of the field * - ``alias`` - string - Unique alias of the field used in the Form Field name attributes * - ``description`` - string/null - Description of the field * - ``type`` - string - Field type * - ``group`` - string - Group of the fields where the field belongs * - ``order`` - int - Order number of the field * - ``object`` - string - Which object uses the field, Contact or Company * - ``defaultValue`` - string - Default value of the field * - ``isRequired`` - boolean - ``true`` if this is a required field * - ``isPubliclyUpdatable`` - boolean - ``true`` if public requests can change the field value * - ``isUniqueIdentifier`` - boolean - ``true`` if the field is a unique identifier * - ``properties`` - array - Field options if the field type needs some. **Response** If using ``PUT``, the expected response code is ``200`` if editing the field or ``201`` if creating the field. If using ``PATCH``, the expected response code is ``200``. **Properties** Same as `Get Field <#get-field>`_. Delete field ************ .. vale on .. code-block:: php delete($id); Delete a field. .. vale off **HTTP Request** .. vale on ``DELETE /fields/contact/ID/delete`` or ``DELETE /fields/company/ID/delete`` **Response** ``Expected Response Code: 200`` **Properties** Same as `Get Field <#get-field>`_.