update
This allows you to update values on fields on your applicants forms. This is broadly similar to get_info, except that its scope is limited to updating fields and does not include system fields (anything which starts with an underscore, such as _usercart). For adding products see add_product.
Parameters
Name | Type | Required | Description |
|---|---|---|---|
fields | string, integer, or array | true | These are the fields present in your forms. See the section "Fields" for more. |
submit_forms | boolean | false | This prevents the user's forms from submitting. This is generally advised if you want to prevent the update from activating triggers that are set in your project. false will prevent the forms from submitting, but true is the default. |
mark_forms_complete | array or string | false | Marks the user's forms complete. Pass an array of form ids, or "all" (as a string value) for every form the user has in their current form set. Only valid on action: update. See section for mark_forms_complete below for more. |
Example
curl -X POST "https://www.regpack.com/reg/api2/users/" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Api-Id: 15263" \
-H "Api-user: [email protected]" \
-H "Api-Token: cd2e514f-7gab-3cde-62fg-51abcd4e7362" \
-d '{
"action": "update",
"group_id": 100909072,
"clogin_id": 102670541,
"connected_to": 102670540,
"doc": {
"your_instrument": "piano",
"will_you_record_an_album_with_jimi_hendrix": [
"no"
],
"f_251473_6251473": "a field id looks like f_251473_6251473 by default, and has words like your_instrument only when you map it"
}
}
Response
{
"msg": "User updated.",
"system_action": [
"user_updated"
],
"success": true,
"user_info": {
"clogin_id": "102715741",
"group_id": "100909072",
"connected_to": "102715741"
},
"meta_info": {
"u_name": "Jim Hall",
"total_forms": "2",
"completed_forms": "0",
"total_user_forms": "2",
"total_completed_user_forms": "0",
"total_user_mandatory_forms": "2",
"total_completed_user_mandatory_forms": "0",
"total_order": "0.00",
"total_paid": "0.00",
"total_balance": "0.00",
"status_id": "0",
"status_name": null,
"status_color": null,
"application_date": "Dec 8th 2021 17:20",
"application_date_raw": "2021-12-08 17:20:08",
"u_comments": "0",
"group_id": "100909072",
"uid": "4085257",
"clogin_id": "102715741",
"excluded": "0",
"connected_to": "102715741",
"total_user_tags": "0",
"user_tag_ids": null,
"total_non_excluded_children": "0",
"star": "0",
"admin_initials": null,
"admin_color": null,
"assigned_admin_id": null
}
}mark_forms_complete
mark_forms_complete is a top-level field of the request (a sibling of action, group_id, clogin_id, connected_to, and doc), and it is only used while action: update. It marks one or more of a user's forms as complete — the same "complete" state a form reaches when the user finishes and submits it in the browser. This is useful when you set a user's data through the API and want their forms to show as complete without the user having to open and submit each one.
It accepts either an array of form ids (mark exactly those forms complete) or the string "all"(mark every form the user currently has complete). Only forms that belong to the user — the clogin_id within group_id — can be marked complete; any other ids are ignored and returned under skipped, each with a reason, such as the id not being in the user's form list. The call is idempotent: marking an already-complete form complete does nothing, and it never un-completes a form, so it is safe to call repeatedly.
A form can be marked complete even if some of its mandatory fields are still empty. The call still succeeds and the form is marked complete, and a message is added to notices identifying the form and the first missing field, so you are aware.
doc is optional when you use mark_forms_complete — you can send the field on its own, with no field values, just to mark forms complete. When both doc field values and mark_forms_complete are sent in one call, the field values are saved first, then the forms are marked complete.
Mark specific forms complete
Sending a list of form id's allows you to mark those forms complete. Note the call below also happens to include field values ("your_instrument": "piano"). When both doc field values and mark_forms_complete are sent in one call, the field values are saved first, then the forms are marked complete.
Request:
curl -X POST "https://www.regpack.com/reg/api2/users/" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Api-Id: 15263" \
-H "Api-User: [email protected]" \
-H "Api-Token: cd2e514f-7gab-3cde-62fg-51abcd4e7362" \
-d '{
"action": "update",
"group_id": 100909072,
"clogin_id": 102670541,
"connected_to": 102670540,
"doc": {
"your_instrument": "piano"
},
"mark_forms_complete": [250943, 250960]
}'Response:
{
"success": true,
"msg": "Information updated",
"marked_complete": ["250943", "250960"],
"skipped": [],
"notices": []
}Mark every form the user has complete
When "all" is sent as a string, all of the forms in the user's current form set will be marked complete.
Request
curl -X POST "https://www.regpack.com/reg/api2/users/" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Api-Id: 15263" \
-H "Api-User: [email protected]" \
-H "Api-Token: cd2e514f-7gab-3cde-62fg-51abcd4e7362" \
-d '{
"action": "update",
"group_id": 100909072,
"clogin_id": 102670541,
"connected_to": 102670540,
"mark_forms_complete": "all"
}'Response:
{
"success": true,
"msg": "Forms marked complete.",
"marked_complete": ["250943", "250960", "250961"],
"skipped": [],
"notices": []
}Response fields added by mark_forms_complete
Field | Type | Meaning |
|---|---|---|
marked_complete | array of form id strings | Forms that were marked complete. |
skipped | array of { form_id, reason } | Ids that were not marked complete (for example, the user does not have that form). |
notices | array of strings | Informational messages, such as a form that was marked complete while it still has empty mandatory fields. |
Validation and Troubleshooting
It is important to note that there are a number of behind-the-scenes validation actions that are occurring whenever you attempt to update a user via the API. To get an overview of the basic validation options for each type of field make sure to check out the section on fields.
Situations in which no updates occur
There are three common scenarios in which an update call will be made, but no information will be updated for the user.
- If you attempt to update a user that does not exist in the project, the system will not update any information.
- If you attempt to update a user that does exist but the answer to the field (such as a multiple-choice answer; see more below) or the field itself does not exist, then the system will not update any information.
- Finally, if you attempt to update a user who does exist but they do not have the form that contains the field you are trying to update, then the system will not update any information.
Additional multi-select validation
As mentioned in the section on fields, multiple-choice fields should be sent in the API as an array of strings where a single answer update is an array of length one. When a string within this array is parsed, we first test whether the string matches any of the existing values within that field. If no match can be found, then the HTML is stripped from the string, and the entire string is converted to lowercase. If after this the string still doesn't match any of the values within your project, then the system would proceed to not update the value.
The trouble with triggers
If a call is otherwise correct and you set submit_forms to false, then a few specific things happen: The value will save as expected, and the form on which the field exists will not submit for the user. The effect this has in practice is that it prevents subsequent triggers within forms, emails, products, etc. from reacting to the submission of the form. This being said, if there are any fields that are triggered to show within the form itself in response to the value you are updating, then those triggers will still activate. Generally this is not a big deal, and the emails, products, or subsequent forms are the things you're worried about activating.