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.

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
    ],
  ]
]

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 )

PreviousList of Endpoints NextGet Post

Last updated 5 months ago

Was this helpful?

text

boolean

key_select

multi_select

link

tags

communication_channel

date

datetime

user_select

number

location_grid

location_grid_meta (Mapbox)

connection

connection meta

Creating a post from a connection field

post_user_meta

Fields example together