Lookup Object

Extract information from a Procore object.

This action can be used to execute most Procore API calls that use an HTTP GET request and return a single object (rather than an array of objects). Please refer to the Procore API Reference to find such APIs; most of them begin with the word "Show". Here are just a handful of Procore APIs that you can invoke with this action:

Inputs

KeyValue
apiPathRequiredThe Procore API endpoint that you wish to invoke, without the "vapid" prefix. Please refer to the Procore Actions overview for more on the apiPath input, which is required for all Procore Actions.
field_<any_string>Required (at least one)The name of a field to be retrieved from the Procore object specified in the apiPath. The key can be anything starting with “field_”, while the value must be a Procore field name. To get a list of all possible field names, look at the Responses section of the corresponding Procore API documentation. Any key from the JSON response can be used as a field name. For instance, for the Show Company User API, field names include address, avatar, business_phone, business_phone_extension, etc.

To reference subfields, use dot notation. For instance, in the Show Company User API, to reference the name key within the vendor group, you would use “vendor.name”.
fieldType_<any_string>OptionalThe data type of the field that was retrieved from Procore using the corresponding field_<any_string> input. Only the date and datetime data types need to be specified in this way. This is necessary to determine which fields should be converted to the specified timeZone.

Refer to the Responses section of your Procore API's documentation to determine which fields are of type date or datetime.
timeZoneOptionalThe time zone in which any date or datetime fields should be returned. These fields will be converted from the time zone used in the Procore Project to the time zone you specify. If time zone is not specified, all dates/times will be returned in UTC time. See the Zone ID column here for a list of accepted values for the timeZone input.

This input is unnecessary if no date or datetime fields are retrieved.

Outputs

KeyValue
field_<any_string>The value retrieved by the corresponding field_<any_string> input. So if the key is field_BusinessPhone, then this will be the value of the Procore field retrieved by the field_BusinessPhone input.

Usage Example

A common purpose of looking up information from a Procore object is to use it to pre-populate some fields in a GoFormz form or other GoFormz object. For this reason, the Lookup action is typically used in conjunction with actions like Create Form, Update Form, Add Data Source Rows, etc. Those actions then reference the outputs of this Lookup Object step.

Suppose you are using a Procore Webhook to dispatch a GoFormz form when a new Incident is created in Procore, and you want to pre-fill this form with some information. One of the fields you want to pre-fill is the name and contact information of the Safety Manager on the project. Here is how you might go about retrieving this data.

Your workflow would start with the Procore Event trigger, which listens for the Procore Webhook to initiate the workflow. Then you might use the Query action to get information about the project's Safety Manager, and the Filter DataSet and Select DataSet Row actions to extract the Safety Manager's user ID from the DataSet file returned by the Query action. After this, you might use this Lookup Object action with the following inputs:

KeyValue
apiPath/companies/#{trigger.company_id}/users/#{selectSafetyManager.field_contact_id}
field_first_namefirst_name
field_last_namelast_name
field_mobile_phonemobile_phone
field_email_addressemail_address
field_job_titlejob_title
field_created_atcreated_at
fieldType_created_atdatetime
timeZoneAmerica/Tijuana

We use Procore's Show Company User API here. We construct the apiPath as described in the API documentation, using the company ID output from the Webhook trigger and the Safety Manager's user ID from the selectSafetyManager workflow step to fill in the required path parameters.

Next, we retrieve the fields that we want from the user object — first_name, last_name, mobile_phone, email_address, job_title and created_at. Notice that all of these fields can be found in the Responses section of the API documentation. Since the created_at field is a date/time, we specify its field type as such and also specify the time zone in which we want the date and time to be returned.

Finally, you may end your workflow by creating a new form with Create Form and using the information retrieved by this Lookup Object step to pre-fill the Safety Manager's name and contact information in the appropriate form fields.