Fields Format

Fields have different types. Each type will need it's own syntax. The list of fields will changed based on your D.T instance. For a list of available fields have a look at: the field explorer tool under Utilities in your wp-admin.

Note: For creation and update endpoints, the do_not_overwrite_existing_fields parameter prevents overwriting existing field values. See the Create Post and Update Post documentation for details.

text

Field examples:

• title

fields = [
  "title" => "John Doe"
]

boolean

Field examples:

• update_required

fields = [
   "update_required" => true
]

key_select

Field examples:

• overall_status

• seeker_path

The key is used to set save the field instead of the value.

fields = [
   "overall_status" => "active"
]

multi_select

Field examples:

• sources

• milestones

$fields = [
  "sources" => [
    "values" => [
      [ "value" => "web" ],  //set a value, the value must be predefined in the field options
      [ "value" => "phone", "delete" => true ] //remove existing
    ],
    "force_values" => false // true will set source to the values entries. removing all others
  ]
]

link

Field examples:

• none as yet

$fields = [
  "social_links" => [
    "values" => [ 
      [  "type" => "fb", "value" => "facebook.com" ],  //set a value, the type must be predefined in the field options
      [  "type" => "twitter", "value" => "twitter.com", "meta_id" => "1234" ],  //update a value
      [ "meta_id" => "1234", "delete" => true ] //remove existing
    ],
  ]
]

tags

Field examples:

• tags

Functions just like multi_select, but without requiring a pre-defined list of values.

$fields = [
  "tags" => [
    "values" => [
      [ "value" => "web" ],
      [ "value" => "phone", "delete" => true ] //remove existing
    ],
    "force_values" => false // true will set tags to the values entries. removing all others
  ]
]

communication_channel

• contact_phone

• contact_email

• contact_address

• contact_facebook

• etc

Note: The field name must start with contact_

There are three actions you can take:

• Create, if you don't include a key, a new field will be created

• Update, include the key and value to update

• Delete, including the key and the delete flag will remove the Phone number

$fields = [
  "contact_phone" => [
    ["value" => "94 39 29 39"], //create
    ["key" => "contact_phone_123", "value" => "43 42 45 43"],  //update
    ["key" => "contact_phone_123", "delete" => true] //delete
  ]
]

To change a detail on a contact method:

$fields = [
  "contact_phone" => [
    ["key" => "contact_phone_123", "verified" => true],  //update verified flag
  ]
]

If either Mapbox or Google Geocode APIs are available, the contact_address field can also be instructed to support the auto-geolocating of manually entered addresses, with the use of a geolocate boolean flag.

$fields = [
  "contact_address" => [
    ["value" => "Poland", "geolocate" => true] //create
  ]
]

date

• baptism_date

Can be either a date string or a numeric timestamp.

$fields = [
  "baptism_date" => "2018-12-31" //format yyyy-mm-dd
]

$fields = [
  "baptism_date" => 946720800 //timestamp
]

datetime

• meeting_time

Can be either a date string or a numeric timestamp.

If sent as a date string, care must be taken with timezones etc.

If a timezone isn't sent in the time string, the timezone will be assumed, so it is recommended to include the timezone information in the date string to get a precise timestamp.

Use the time formats on here PHP DateTime Formats for the timestring format

$fields = [
  "meeting_time" => "2018-12-31 12:15 pm GMT-06:00" //format yyyy-mm-dd hh:MM timezone-adjustment
]

$fields = [
  "meeting_time" => 946720800 //timestamp
]

user_select

• assigned_to //int, a user id

$fields = [
   "assigned_to" => 4  //the id of the user
]

number

• quick_button_no_answer

• quick_button_contact_established

• quick_button_meeting_scheduled

• quick_button_meeting_complete

• quick_button_no_show

$fields = [
  "quick_button_no_answer" => 3
]

If the number is greater than the max_option or less than the min_option for this field, an error will be returned

location_grid

• location_grid

$fields = [
  "location_grid" => [ 
    "values" => [ 
      [ "value" => '100089589' ] //France
    ],
    "force_values" => false // true will set locations to the values entries. removing all others
  ] 
]

location_grid_meta (Mapbox)

• location_grid_meta

You can submit geolocation information to the API using the Mapbox service in three ways.

(1) Submit using a known grid_id

$fields = [
  'location_grid_meta' => [
    'values' => [
      [
        'grid_id' => 100000020
      ]
    ],
    "force_values" => false // true will set locations to the values entries. removing all others
  ]
];

(2) Submit using longitude, latitude, location label, and location level information

$fields = [
  'location_grid_meta' => [
    'values' => [
      [
        "label" => "Kunduz, Afganistan",
        "level" => "admin1",
        "lng" => 68.7514,
        "lat" => 36.8396,
      ]
    ],
    "force_values" => false // true will set locations to the values entries. removing all others
  ]
];

(3) Submit using just longitude and latitude

$fields = [
  'location_grid_meta' => [
    'values' => [
      [
        "lng" => 68.7514,
        "lat" => 36.8396,
      ]
    ],
    "force_values" => false // true will set locations to the values entries. removing all others
  ]
];

Submitting location_grid_meta will trigger the mapping service to geocode the information to the location grid and install records in the correct tables. This allows for more advanced location storage and mapping.

connection

• groups

• people_groups

• baptized_by

• baptized

• coaching

• coached_by

• subassigned

• relation

Let's say our contact is connected to groups with IDs 1, 3 and 43. This example will add the group with ID 1 and will remove the group with ID 43. The contact will then be connected to group 1 and 3

$fields = [
  "groups" => [
    "values" => [
      [ "value" => 1 ],
      [ "value" => 43, "delete" => true ]
    ],
    "force_values" => false // true will set groups to the values entries. removing all others
  ]
]

This example will remove groups 1 and 3 and leave the contact connected to group 5:

$fields = [
  "groups" => [
    "values" => [
      [ "value" => 5 ],
    ],
    "force_values" => true // true will set groups to the values entries. removing all others
  ]
]

connection meta

Add meta data when creating or updating a connection value. Here we add the role and date meta to the group member.

$fields = [
  "groups" => [
    "values" => [
      [
        "value" => 5,
        "meta" => [
          "role" => "treasurer",
          "date" => time()
        ]
      ],
    ],
  ]
]

Use the same syntax for creating or updating a connection. To delete a connection meta send an empty string:

$fields = [
  "groups" => [
    "values" => [
      [
        "value" => 5,
        "meta" => [
          "role" => "",
          "date" => ""
        ]
      ],
    ],
  ]
]

Creating a post from a connection field

Example: Cantact A baptized someone (not yet a contact in the system). We can use the additional_meta parameter to create the new contact and set the baptized_by field by passing in the baptized connection field key. When creating the new contact, the API with translate baptized to baptized_by and set the new contact to be baptized by Contact A.

$fields = [
  "additional_meta": [
    "created_from": 45, //the id of the existing record you want use in the connection
    "add_connection": "baptized", //the connection field where the new record is created from
  ]
]

post_user_meta

Meta for a post for a specific user. This meta is only accessible by the user who created it and is stored in its own table.

• reminders

$fields = [
  "reminders" => [
    "values" => [
      [ "value" => "Call again" ],
      [ "value" => "Call again", date => "2018-01-01" ], //optional date value
      [ "id" => 43, "delete" => true ] //delete user the meta id.
    ]
  ]
]

Fields example together

$fields = [
  "title" => "Bob",
  "overall_status" => "active",
  "contact_phone" => [
    ["value" => "43 42 45 43"],
    ["value" => "94 39 29 39"]
  ],
  "locations" => [
    "values" => [
      [ "value" => "9" ]
    ]
  ],
  "quick_button_no_answer" => 3,
  "baptism_date" => "2017-11-34",
]
DT_Posts::create_post( 'contacts', $fields )